Skip to content

Manage Service Accounts

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

For an overview of service accounts and how to use them, see Service Accounts.

The endpoints⚓︎

Endpoint Description
/service_accounts/ Supports listing, creating, retrieving, and deleting service accounts, as well as generating and revoking tokens.
/service_account_tokens/ Lists the service account token metadata for all service accounts. Use query parameters for ordering, pagination, and to narrow results by revocation status or service account UUID.

For operations on user accounts, see API endpoints for users and service accounts.

Manage service accounts⚓︎

Action UI API
View a service account View in UI View with API
Create a service account Create in UI Create with API
Assign roles Assign roles in UI Assign roles with API
Issue a token Issue token in UI Issue token with API
View token metadata Unavailable List token metadata
Revoke tokens Unavailable Revoke tokens with API
Delete a service account Delete in UI Delete with API

View service accounts⚓︎

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.

View available actions on existing service accounts

View with API⚓︎

Show a single service account or list all.

List all service accounts⚓︎

Use the endpoint List service accounts.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "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.

1
2
3
4
5
6
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}"

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

Create service accounts⚓︎

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.

Use left flyout to create a new service account

  1. Enter a unique service account name.
  2. Click Create & Continue.

Workflow step to create and name a service account

400 response code

If you receive a 400 response code and the message Invalid service account name, make sure the Account name field conforms to the service account name restrictions.

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.

Create with API⚓︎

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

1
2
3
4
5
6
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/"

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

Service account name restrictions⚓︎

Hydrolix enforces the following requirements on service account names:

  1. Minimum length: 3
  2. Maximum length: 256 (v6.0 and above). 64 (v5.11 and below)
  3. Valid characters: Characters must be lowercase ASCII letters, digits, hyphens, and underscores.
  4. Uniqueness: The service account name must be unique.
  5. Immutability: The service account name can't be changed once set.

Assign roles⚓︎

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.

Workflow step to assign RBAC roles to a service account

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

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.

1
2
3
4
5
6
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/"

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

Service account tokens⚓︎

The following sections discuss how to create, list, and revoke tokens associated with service accounts.

Issue token in the UI⚓︎

For information about token expiration and validity, 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. To specify a custom expiration date, see Issue 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 Issue 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.

Issue an authorization token for a service account

Issue token with the API⚓︎

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

1
2
3
4
5
6
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.

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

List token metadata⚓︎

Version availability

This feature was introduced in Hydrolix version 6.0.

Use the config/v1/service_account_tokens endpoint to see which tokens are still valid and plan rotation before a token expires.

To retrieve tracked tokens across all service accounts:

1
2
curl "${HDX_HYDROLIX_URL}/config/v1/service_account_tokens/" \
  --header "Authorization: Bearer ${HDX_TOKEN}" | jq

1
2
curl "${HDX_HYDROLIX_URL}/config/v1/service_account_tokens?page=1&page_size=5" \
--header "Authorization: Bearer ${HDX_TOKEN}" | jq

You can filter the results by providing the service account UUID as a query parameter:

1
2
curl "${HDX_HYDROLIX_URL}/config/v1/service_account_tokens?service_account=${HDX_SA_UUID}" \
  --header "Authorization: Bearer ${HDX_TOKEN}" | jq

You can further filter the results by revocation status and order them by issue time or expiry:

1
2
3
4
5
6
7
curl --fail --silent --get \
  --header "Authorization: Bearer ${HDX_TOKEN}" \
  --data "service_account=${HDX_SA_UUID}" \
  --data "revoked=false" \
  --data "ordering=expiry" \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_account_tokens/" \
  | jq .

Revoke tokens⚓︎

Revoke tokens in the UI⚓︎

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

Consider these options instead:

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

Revoke a single token with the API⚓︎

The endpoint to invalidate a service account token revokes one token associated with a service account. Successful revocation returns the token's identifying information and the field revoked: true.

1
2
3
4
5
curl --fail \
  --request DELETE \
  --header "authorization: Bearer ${HDX_TOKEN}" \
  --header "content-type: application/json" \
  -- "${HDX_HYDROLIX_URL}/config/v1/service_account_tokens/${SA_TOKEN_UUID}"

1
2
3
4
5
6
7
8
9
{
"uuid": "286c1b52-4d12-435e-9da6-8ae4a391b26b",
"created": "2026-06-01T22:04:12.726700Z",
"modified": "2026-06-09T21:37:10.849408Z",
"expiry": "2027-06-01T22:04:12.686584Z",
"issued": "2026-06-01T22:04:12.718836Z",
"revoked": true,
"service_account": "1dae0ff6-d798-46cb-91e3-ba7848b7702f"
}

Revoke all tokens with the API⚓︎

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

1
2
3
4
5
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.

View token issue and expiration dates⚓︎

Use the API to View Token Expiry for v6.0 and Above Tokens

The JWT decoder instructions work for viewing expiration dates of all tokens.

For untracked tokens issued using Hydrolix cluster versions earlier than v6.0, no identifying information remains in the cluster. Use the JWT decoder to determine expiry.

For tracked tokens issued using Hydrolix v6.0 and later, use the /service_account_tokens/ endpoint. See List token metadata.

Service account tokens are JSON Web Tokens (JWTs) that contain an expiration timestamp in the exp field. Decode the token locally using any JWT decoder.

The following examples extract the issue time and expiration time from a service account token stored in $HDX_SERVICE_TOKEN.

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import base64
import json
import os
from datetime import datetime, timezone

token = os.environ["HDX_SERVICE_TOKEN"]
payload = token.split(".")[1]
payload += "=" * (4 - len(payload) % 4)
decoded = json.loads(base64.urlsafe_b64decode(payload))

issued = datetime.fromtimestamp(decoded["iat"], tz=timezone.utc)
expires = datetime.fromtimestamp(decoded["exp"], tz=timezone.utc)
print(f"Issued:  {issued.isoformat()}")
print(f"Expires: {expires.isoformat()}")
Decode Token Expiration With Bash and jq
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
PAYLOAD=$(echo -n "${HDX_SERVICE_TOKEN}" | cut -d. -f2)
PAD=$(( 4 - ${#PAYLOAD} % 4 ))
if [ "$PAD" -lt 4 ]; then
  PAYLOAD="${PAYLOAD}$(printf '%0.s=' $(seq 1 $PAD))"
fi

echo "$PAYLOAD" \
  | tr '_-' '/+' \
  | base64 --decode \
  | jq '{issued: (.iat | floor | todate), expires: (.exp | floor | todate)}'

Example output:

Python Output
1
2
  Issued:  2026-02-24T22:39:07.874900+00:00
  Expires: 2027-02-24T22:39:07.829358+00:00
Bash Output
1
2
3
4
{
  "issued": "2026-02-24T22:39:07Z",
  "expires": "2027-02-24T22:39:07Z"
}

Get tracked and untracked tokens for a service account⚓︎

Prior to v6.0, Hydrolix didn't store identifying information about issued tokens. These tokens are referred to as "untracked." Untracked tokens may still be valid and therefore can be used for authorization.

Any token returned by the list token metadata endpoint was created with a v6.0 or above Hydrolix cluster and is a tracked token.

To determine if a service account has any untracked tokens, use the GET /service_accounts endpoint.

1
2
curl "${HDX_HYDROLIX_URL}/config/v1/service_accounts/${HDX_SA_UUID}/" \
--header "Authorization: Bearer ${HDX_TOKEN}" | jq

For example:

1
2
curl "https://hostname.hydrolix.live/config/v1/service_accounts/1dae0ff6-d798-46cb-91e3-ba7848b7702f/" \
  --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJWTTkwM2NmsbbEUB3g30AbTVEgMA" | jq

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "uuid": "1dae0ff6-d798-46cb-91e3-ba7848b7702f",
  "audit": true,
  "is_service_account": true,
  "name": "test-service-account",
  "description": "My name is account. Service account.",
  "roles": [
    "read_only"
  ],
  "untracked_token_count": 2
}

Delete service accounts⚓︎

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.

Delete a service account

Delete with API⚓︎

The endpoint Delete service account removes the service account.

1
2
3
4
5
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.

API reference information⚓︎

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

API example variables⚓︎

Shell variable Contents
$HDX_HOSTNAME The fully qualified domain name (FQDN) of the cluster
$HDX_HYDROLIX_URL The base URL of the cluster
$HDX_USER Username for authenticating to the API, to fetch an authorization token
$HDX_PASSWORD Password for authenticating to the API, to fetch an authorization token
$HDX_TOKEN A user token. User account must have service account permissions
$HDX_SA_UUID The service account UUID, needed for API calls operating on a specific service account
$HDX_SERVICE_TOKEN A service token returned in the response from the Create service account endpoint

Obtain a user token to execute the examples below. For authentication methods and endpoint details, see Introduction to the Config API.

API workflow steps⚓︎

  1. Acquire an authorization token using Login to Hydrolix. For authentication patterns and token usage, see Acquire authorization 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. Issue 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.

Log in 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:

1
2
3
4
5
6
7
8
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"
)

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 authorization token.

In this step, test with a service account token.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "uuid": "43f50883-2d96-4faf-acb2-ca1b57faa667",
  "orgs": [],
  "roles": [
    "read_only"
  ],
  "audit": true,
  "emailVerified": false,
  "enabled": true,
  "is_service_account": true,
  "name": "example-service-account-name"
}

Troubleshoot⚓︎

  • 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.
  • When creating a service account, if you receive a 400 response code, ensure the service account conforms to the service account name restrictions.
  • Clusters running Hydrolix v6.0 and above with service accounts whose names exceed 64 characters can't downgrade to v5.11 or below. Operators must remove or rename those accounts before downgrading. See v6.0 downgrade restrictions