Skip to content

Service Accounts Overview

This page describes service account concepts and how to use service account tokens.

Service accounts

  • exist at the global scope in a cluster
  • have defined permissions in a specific cluster and aren't associated with any user accounts
  • use authorization tokens as the sole mechanism for gaining access to a cluster
  • can exist without currently valid tokens
  • can't be disabled; they must be deleted

To create and manage service accounts, see Manage Service Accounts.

For the permissions needed to create and manage service accounts, see Required permissions.

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. For instructions on creating and assigning roles, see RBAC How-to.

Management tasks⚓︎

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
Generate a token Generate token in UI Generate token with API
Revoke tokens Revoke tokens in UI Revoke tokens with API
Delete a service account Delete in UI Delete with API

Use service accounts⚓︎

Service accounts gain access solely using authorization tokens.

The service account username is never used when connecting to the Hydrolix cluster.

For HTTP services, use the HTTP header Authorization: Bearer $AUTH_TOKEN. For information about token format and lifetime, see Authorization tokens.

For non-HTTP services, use the special username __api_token__ and place the authorization token in the password field.

For connection examples using the __api_token__ pattern, see MySQL Client and ClickHouse.

Configure datasources in visualization tools⚓︎

After creating a service account and generating a token, configure datasources in visualization tools.

Grafana⚓︎

For detailed instructions on configuring Grafana with service accounts, including authentication patterns and circuit breaker settings, see Hydrolix Data Source Plugin for Grafana.

Other visualization tools⚓︎

For Superset, Kibana, and other tools that use the __api_token__ authentication pattern:

  • Username: __api_token__
  • Password: The service account token (the full JWT token value)

Consult the datasource configuration documentation for additional connection parameters.