Create Service Accounts for Programmatic and CI/CD Access

Service accounts represent applications or CI/CD systems that access Kestra programmatically, without a password or UI access. Each service account has a name, an optional description, an optional group assignment, and a list of roles that grant it permissions to specific resources.

Service accounts vs. users

Service accounts have no password and no access to the Kestra UI — they authenticate exclusively via API token. Users, by contrast, can interact with both the UI and the API using a password or an API token.

Creating a service account

Service accounts are created under IAM → Service Accounts. Each has a name, optional description, optional group assignment, and roles that grant access to specific resources. API tokens are generated from the service account’s details view and are shown only at creation.

Users, service accounts, and API tokens

You can create an API token for a regular user as well. While service accounts are recommended for programmatic access from CI/CD or external applications, user API tokens are useful when you want programmatic actions to be tracked and audited against a specific person.

The key difference: a service account has no password or personal information and is authenticated exclusively with an API token. A user can interact with both the UI and the API, using either a password or an API token.

Allocating service accounts to groups

Each service account can be attached to one or more groups, such as a “Bots” group that centrally governs programmatic access for CI/CD across multiple projects with a single role.

CLI token usage

The Kestra CLI accepts an API token via --api-token:

./kestra namespace files update prod scripts . \
--server=https://demo.kestra.io --api-token yourtoken

Basic Auth credentials are passed via --user:

./kestra namespace files update prod scripts . \
--server=https://demo.kestra.io --user=rick.astely@kestra.io:password42

Service account name convention

Follow the DNS naming convention when naming service accounts. The name property must:

• contain at most 63 characters
• contain only lowercase alphanumeric characters or hyphens (-)
• start with an alphanumeric character
• end with an alphanumeric character.

Examples:

• ✅ my-service-account is a valid name
• ✅ my-service-account-1 is a valid name
• ❌ MY_SERVICE_ACCOUNT is not a valid name because it contains uppercase characters and underscores
• ❌ myServiceAccount is not a valid name because it contains uppercase characters and camel case
• ❌ my-service-account- is not a valid name because it ends with a hyphen.

Kestra uses the DNS-style naming convention so that service account names remain valid across contexts where they may be forwarded, such as Kubernetes pod labels.