Service Users
Overview
A Service User is a type of user that is intended to be used by customer systems that have a requirement to access Instaclustr APIs. Service Users can have access keys for Instaclustr APIs but do not have Instaclustr console login credentials and cannot use the Console. A typical use case for Service Users is for applications running in a server environment to automate monitoring or provisioning operations.
Each Service User has one or more Administrators. These are human users that administer the Service Users (generating and rotating API keys).
Getting started with Service Users
Service Users can be created via the Instaclustr Console or API. Service Users are created in, and have access to, a single account. This account is the account used when creating the Service User through the console or the account associated with the API key that was used to create the Service User via the API.
A Service User can be created with READ_ONLY, CLUSTER_ADMIN, and OWNER profiles. READ_ONLY allows them to view cluster details and monitoring, CLUSTER_ADMIN to manage clusters, and OWNER to manage users (excluding Service Users). A user can only create a Service User with the same or lower access levels than they have themselves.
You can view the list of Service Users on the console, manage their API keys and Administrators, and create new Service Users.
Owner and Cluster Admin level users in an account can create Service Users. The user who creates a Service User automatically becomes an Administrator of that user. Administrators of a Service User may invite additional Cluster Admin users to be Administrators of that user. Owner users in an account automatically have Administrator-level access to all Service Users in that account.
If the Administrator is revoked from an account, they lose access to every Service User they previously administered in that account.
Service users may rotate their own API keys using our rotate API key endpoint. For details, refer to the API reference documentation.
On the console, service users’ api keys may be rotated and restricted to specific networks. For details, refer to the API key documentation.
API Example
To create a Service User, send a POST request to https://api.instaclustr.com/v1/service-users with the following request data as JSON.
|
1 2 3 4 5 6 |
{ "username": "service_user", "displayName": "RO service user", "profile": "READ_ONLY" } |
Upon a successful request, the endpoint will return a 201 response with the created. READ_ONLY Service User’s information, which includes the API keys.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
{ "username": "service_user", "displayName": "RO service user", "role": "READ_ONLY", "apiKeys": { "apiKeys": [ { "username": "service_user", "account": "ca441710-e249-4be2-9892-3268358f9a5e", "keyType": "MONITORING", "key": "efababd41583c0248ec8a448f350408" }, { "username": "service_user", "account": "ca441710-e249-4be2-9892-3268358f9a5e", "keyType": "PROVISIONING_READONLY", "key": "13aa5048ec8a765569cc5f6568265568" } ], "allowedApiKeys": [ { "name": "MONITORING", "displayName": "Monitoring" }, { "name": "PROVISIONING_READONLY", "displayName": "Read Only Provisioning" } ] }, "administrators": [ "human_user" ] } |
This Service User can now be used as a read-only user of the account with the API keys.
To view the full API reference, navigate to this documentation.
Security
Service Users are designed to provide a more secure alternative for API authentication than sharing keys associated with an individual. Some key security features of Service Users to be aware of are:
- Service Users are not able to log in via console, and the only form of authentication is via API.
- Administrators can manage the API keys of their Service Users, meaning that they are able to revoke or rotate an API key at any time.
- Administrators receive email notifications on security related activities on the Service Users. Specifically, these notifications are sent on API key revoke and generation.
- The Service Users feature is compatible with PCI enabled accounts.
Available API Endpoints
The Service User API can be used by an Owner or Cluster Admin of an account for the Service Users feature. The following provides a brief overview of relevant endpoints. For a complete reference see the API documentation.
Create a Service User
This POST endpoint takes in a JSON request body to define the Service User’s username, display name, email, and role. Note that a Cluster Admin cannot create a Service User with the Owner role.
Update a Service User
This PUT endpoint can be used to update a Service User. The fields that can be updated are the display name, role, and the administrators. Note that it is not allowed to add an administrator that is not either Owner or Cluster Admin. Owner users can update any Service User within the account, however Cluster Admin must be an administrator of the Service User to perform an update.
Delete a Service User
This DELETE endpoint can be used to delete a Service User. Owner users can delete any Service User within the account, however Cluster Admin must be an administrator of the Service User.
API Keys
Generate / Revoke
This endpoint accepts POST and DELETE methods. Both methods require a JSON body to define the API key type. A POST request generates, and a DELETE request revokes an API key of the defined type (e.g. PROVISIONING, MONITORING)
Rotate
Service users may also use the self-rotate endpoint to rotate their own API keys so that they can change without human interaction. The API key used to authenticate the request to this endpoint will be regenerated and the new key will be returned in the response.
By Instaclustr Support