Service Accounts How-to

Managing service accounts

Service accounts exist with defined permissions in a specific cluster and aren't associated with any user accounts.

Authorization tokens are the sole mechanism by which service accounts can gain access to a cluster.

This page describes how to create, manage, and delete service accounts and their corresponding auth tokens using both the Hydrolix UI and the Config API.

Service account overview

Service accounts are easy to create and delete.

Service accounts themselves exist at the global scope in a cluster. See Required permissions for users needing to manage service accounts.

Service accounts must be deleted as there is no way to disable a service account. Only user accounts can be disabled.

Service account token lifecycle

Tokens and their lifecycle have the following characteristics:

• Each service account can have unlimited valid tokens
• Tokens have a configurable lifetime, determined by the expiry query parameter
• Tokens default to a one year lifetime, 365 days
• Tokens are valid until expiration, revocation, or deletion of the service account
• Token invalidation applies to all tokens associated with the service account

⚠️

All tokens are invalidated

It's not possible to revoke a single token.

Required permissions

Users creating and managing service accounts must have the following permissions at the global scope:

• add_serviceaccount
• delete_serviceaccount
• view_serviceaccount
• tokens_serviceaccount

Additional permissions are required to define and manage roles. See the RBAC How-to.

Quick links

Managing service accounts in the UI

View in UI

Users with the view_serviceaccount permissions can see all service accounts in the cluster.

Tokens are never viewable after generation whether sent to the API or UI. The user creating the token is responsible for secure management of the tokens.

1. Log in to the portal.
2. Click Security in the left sidebar.
3. Click Service Accounts in the top bar.

From this page, use the vertical ellipsis (⋮) on each entry to Add Roles, Create token, or Delete account.

Create in UI

1. In the top right corner of the screen, click the + Add new button.
2. Select the Service Account option in the right sidebar.

3. Enter a unique service account name.
4. Click Create & Continue.

The two subsequent steps in the service account creation workflow support assignment of roles to the service account and generation of a first token. These steps can be skipped and completed later.

Assign roles in UI

By default a service account has no roles at creation. Users must have an initial role, but not service accounts. Use the account permissions (RBAC) system to group permissions into roles to be attached to service or user accounts.

1. Log in to the portal.
2. Click Security in the left sidebar.
3. Click Service Accounts in the top bar.
4. Use the vertical ellipsis (⋮) to select Add Roles.
5. Enter all roles in the Select role multiselect drop-down.
6. Click Assign roles.

Role assignment occurs immediately. Since permissions are checked at time of use, subsequent requests will experience the new permissions.

Generate token in UI

See Service account token lifecycle.

Token lifetime defaults to 365 days. It's not possible to set the expiry date and time using the UI. See also Generate token with API.

1. Log in to the portal.
2. Click Security in the left sidebar.
3. Click Service Accounts in the top bar.
4. Use the vertical ellipsis (⋮) to select Create token.
5. Click Generate token.
6. Collect and save the token somewhere safe. You won't be able to retrieve the token after leaving this page.
7. Click checkbox for I have saved the token.
8. Click Finish setup.

Revoke tokens in UI

It's not possible to revoke or invalidate all tokens associated with a service account with the UI.

Consider the following options:

• Revoke tokens with the API
• Create a new service account and token. Switch clients and applications. Delete the old service account

Delete in UI

1. Log in to the portal.
2. Click Security in the left sidebar.
3. Click Service Accounts in the top bar.
4. Use the vertical ellipsis (⋮) to select Delete account.
5. Confirm the deletion of the service account by typing DELETE in the dialog.

Managing service accounts with the API

Performing all of the actions against the Config API in these examples requires a valid user authorization token.

Common variables used in these examples

Obtain a user token to execute the examples below. See also Intro to Config API.

General workflow

1. Acquire an auth token using Login to Hydrolix. See also acquiring auth tokens.
2. Call Create service account with optional name and save the new UUID in the response.
3. Assign roles to UUID with endpoint Add roles to user.
4. Generate service account tokens.
5. Invalidate service account tokens to block all access to the service account.
6. Delete service account when the account is no longer needed.

Login to the API

Get the bearer token, which is good for the next 24 hours, to authenticate future API calls. This command assumes you've set the $HDX_HOSTNAME, $HDX_USER and $HDX_PASSWORD environment variables:

export HDX_TOKEN=$(
  curl -v -X POST -H "Content-Type: application/json" \
  https://$HDX_HOSTNAME/config/v1/login/ \
  -d "{
    \"username\":\"$HDX_USER\",
    \"password\":\"$HDX_PASSWORD\"  
  }" | jq -r ".auth_token.access_token"
)

View with API

Show a single service account or list all.

List all service accounts

Use the endpoint List service accounts.

curl --fail \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_accounts/"

{
  "next": 0,
  "previous": 0,
  "current": 1,
  "num_pages": 1,
  "count": 2,
  "results": [
    {
      "uuid": "097c6259-9787-4400-b54a-50ecdac36110",
      "audit": true,
      "is_service_account": true,
      "name": "another-service-account"
    },
    {
      "uuid": "e2dc1d11-6d90-4ad4-9ec6-a62c8a689d66",
      "audit": true,
      "is_service_account": true,
      "name": "hydrolix-service-user"
    }
  ]
}

Request a specific service account by its UUID

Use the endpoint Retrieve service account with the service account UUID in the URL.

HDX_SA_UUID=e2dc1d11-6d90-4ad4-9ec6-a62c8a689d66

curl --fail \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_accounts/${HDX_SA_UUID}"

{
  "uuid": "e2dc1d11-6d90-4ad4-9ec6-a62c8a689d66",
  "audit": true,
  "is_service_account": true,
  "name": "hydrolix-service-user"
}

Create with API

The endpoint Create service account requires the name attribute in the POST body.

curl --fail \
  --request POST \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  --data '{"name": "example-service-account-name"}' \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_accounts/"

{
  "uuid": "43f50883-2d96-4faf-acb2-ca1b57faa667",
  "audit": true,
  "is_service_account": true,
  "name": "example-service-account-name"
}

Assign roles with API

The endpoint Add roles to user requires the account UUID in the path and a list of roles in the POST body.

curl --fail \
  --request POST \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  --data '{"roles": ["read_only"]}' \
  -- "${HDX_HYDROLIX_URL}/config/v1/users/${HDX_SA_UUID}/add_roles/"

{
  "success": true,
  "message": "1 roles added to service account 43f50883-2d96-4faf-acb2-ca1b57faa667"
}

Generate token with API

The endpoint Generate service account tokens requires the account UUID in the path and supports an optional expiry date-time.

curl --fail \
  --request POST \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  --data '{"expiry": "2025-08-21T14:44:09,428Z"}' \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_accounts/${HDX_SA_UUID}/tokens/"

The optional expiry field must be a valid ISO-8601 formatted datetime at any granularity. The example shows a fully specified Zulu timestamp, but the API will also accept 2025-08-21.

There are no other constraints on the expiry value, allowing creation of very long-lived tokens.

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2RvY3Mtc2FuZGJveC5oeWRyb2xpeC5kZXYvY29uZmlnIiwiYXVkIjoiY29uZmlnLWFwaSIsInN1YiI6IjQzZjUwODgzLTJkOTYtNGZhZi1hY2IyLWNhMWI1N2ZhYTY2NyIsImlhdCI6MTc1NTE4Mjg5OC4yNDI3MDgsImV4cCI6MTc1NTc4NzQ0OS40MjgsImp0aSI6IjMifQ.hUxapK08KdljtINmPTWeCBtx2gZrbJVmmU1zcg_RaaxMf5FQOGL02Vwf34-SNCdBJgZl1KJTjsgF-INOi1SIAQ"
}

Revoke tokens with API

The endpoint Invalidate service account tokens revokes all tokens associated with the service account.

curl --fail \
  --request DELETE \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_accounts/${HDX_SA_UUID}/tokens/"

Upon success, the server returns HTTP status code 204 and no content.

Delete with API

The endpoint Delete service account removes the service account.

curl --fail \
  --request DELETE \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_accounts/${HDX_SA_UUID}/"

Upon success, the server returns HTTP status code 204 and no content.

Verification steps

Verify the token is honored by using the Return information about the authenticated user endpoint. This endpoint reports information for the account linked to the token.

Other examples on this page show the user creating the service account and its tokens which are steps that require a user auth token.

In this step, test with a service account token.

curl --fail \
  --header "authorization: Bearer ${HDX_SERVICE_TOKEN}" \
  --header "content-type: application/json" \
  -- "${HDX_HYDROLIX_URL}/config/v1/users/current/"

{
  "uuid": "43f50883-2d96-4faf-acb2-ca1b57faa667",
  "orgs": [],
  "is_superuser": false,
  "roles": [
    "read_only"
  ],
  "audit": true,
  "emailVerified": false,
  "enabled": true,
  "is_service_account": true,
  "name": "example-service-account-name"
}

Troubleshooting

• Service accounts feature are supported in v5.4 and above. Verify the cluster is running v5.4 or higher.
• Ensure that the user attempting to manage service accounts has the required permissions.
• Ensure that the service account has appropriate permissions. Access is enforced at time of use, so changing roles assigned to an account can be tested without changing an existing token.

Related material

• Account Types
• Authentication and Authorization
• Account Permissions (RBAC)
• RBAC How-to