Create and Control API Tokens for Users and Service Accounts

API tokens grant programmatic access to the Kestra API for users and service accounts.

Where you can use API tokens

Pass a token as a Bearer header to authenticate any Kestra API call — from a CI/CD pipeline, a custom application, or any of the following:

• GitHub Actions
• Terraform Provider
• Kestra Server CLI
• kestractl
• Kestra API

User API tokens

User tokens are created via Settings → API Tokens or the user avatar menu. Each token has a name, optional description, and maximum age. Leaving max age blank creates a non-expiring token. Extended mode resets the expiry on each use. The token is shown only at creation.

Service account API tokens

Service account tokens are created from IAM → Service Accounts: open the service account, select the API Tokens tab, and click Create. The form fields and expiry options are the same as for user tokens.

API request authentication

To authenticate your custom API calls, pass a Bearer token to the request’s Authorization header. The following example triggers a flow execution via the Kestra API:

curl -X POST http://localhost:8080/api/v1/executions/dev/hello-world \
-H "Authorization: Bearer YOUR_API_TOKEN"

How API tokens are secured

An API token is an opaque bearer credential: a cryptographically random value that carries no claims and is not signed. Unlike the JWT session cookie used for interactive UI login, it is not a JWT, and service accounts never use the session cookie.

• At rest, Kestra does not store the token itself. Only a salted SHA-512 hash of the token’s secret is persisted, alongside a short prefix used to identify the token in the UI. The plaintext token is shown only once, at creation, and cannot be retrieved.
• On each request, the presented token is re-hashed and compared against the stored hash in constant time, the owning user or service account must still be active, and the token must not have expired.
• In transit, the token is sent in the Authorization: Bearer header, so API traffic should always run over HTTPS. Treat a token like a password: store it in a secret manager, never commit it to source control, and revoke it if it may have been exposed.