Skip to content

Service API Tokens

When the creation of service API tokens is enabled on a cluster, authorized users may mint long-lived JWTs for service principals to be used for authentication by non-user systems. For example: Service credentials can be used for authentication by CI machines, external data processing systems, and AI agents.

For general authentication setup and maintenance see the Authentication page.

Prerequisites

Required flags

On your cluster's Cluster Status page, check the Options section to make sure the following cluster flags are set as specified.

  • The following flags must be enabled on the cluster:
    • --experimental_jwt_auth=true
    • --experimental_record_generated_credentials=true
    • --allow_service_account_credential_creation=true
  • The cluster must hold a signing key, so it can issue JWTs:
    • --tls_trusted_certificate and --tls_trusted_key must both be set.
    • --mtls_expiration must not be zero. It defaults to 90 days.
  • --security_storage must name a storage backend. Storage is required to record and revoke issued credentials.

Permissions

You must be assigned the built-in global-admin role or a custom role that grants both of the following permissions:

  • http:CreateServiceCredentials, to create the credentials.
  • http:ListAllCredentials, to reach the Admin Settings page.

Creating new Service API JWTs

  1. In your cluster UI, navigate to the Admin Settings page.
  2. In the upper right corner, select the "Create Service API JWT" button.

  3. Fill out the form.

    Principal names must be unique

    Only one valid JWT may be issued at a time. If you create a new JWT for an existing principal name all previously issued JWTs for that principal will be revoked!

  4. Select "Create" to mint and present the JWT.

  5. Copy the JWT text to use for authentication.

    JWT text is fleeting

    This is your only chance to copy the JWT text. Once you close this dialog you can never see the text again. Your EngFlow cluster will retain the ID of this token for revocation purposes but does not record the token itself.

Limitations

  • Service principal names may only contain the characters A-Z, a-z, 0-9, . _ - and must not start with . _ -.
  • Service API tokens may have a duration up to 366 days.
  • Service API tokens are limited to 1 active JWT per service principal name. Creating a new service API token with an identical name will revoke any existing JWT.
  • Services may not be assigned any roles which grant the following permissions:
    • http:CreateServiceCredentials
    • http:GenerateMtlsCertificate
    • http:GenerateJwt
    • http:ListAllCredentials
    • http:RevokeAnyCredentials
    • iam:CreateRole
    • iam:DeleteRole
    • iam:GetRole
    • iam:ListRoles
    • iam:UpdateRole
    • group:Read
    • group:Edit
  • Credentials issued to service whose roles are later modified to allow the aforementioned permissions will no longer be accepted by the EngFlow cluster.

Revocation

Service API tokens are tracked in the same system as credentials created for users. See User credential management for how to revoke credentials.