Skip to main content

Authenticate an application with client credentials

caution

This feature is not yet available. This page is drafted ahead of release and the flow may still change.

A client credential lets an application call the Seqera Platform API as a service account, without holding a person's access token. Issue one when a CI/CD system, a third-party application, or your own back end needs to act in Seqera on its own.

The credential is a client ID and a client secret. The application exchanges the pair for a short-lived access token and sends that token with each API request. The secret itself is never a bearer token, and there is no long-lived token for a service account.

Prerequisites

You need the following:

How a client credential is made up​

Platform gives each service account one OAuth2 client. Its client ID begins with sa_ and does not change. You never create or delete the client yourself.

What you issue and revoke are secrets on that client. A service account can hold two live secrets at once, which is what makes rotation possible without downtime. A secret is live until you revoke it or it expires.

Every secret carries an expiry that you choose when you issue it. None lasts forever.

Issue a client secret​

  1. From the organization page, select Access control, then select the Service accounts tab.
  2. Select the service account, and then the Authentication tab.
  3. Under Client credentials, select Generate secret.
  4. Select an expiry: 30, 90, 180, or 365 days. 90 days is pre-selected.
  5. Select Generate.
  6. Copy the secret and store it where your application reads it from.
caution

The secret is shown once, when you generate it. Platform stores only a one-way hash of it and cannot show it again. If you lose it, revoke the secret and issue another one.

After you close the dialog, the secret appears in the list masked to its last four characters, so you can tell your secrets apart without exposing them. The list also shows each secret's status, when it was created, when it expires, and when it was last used. A secret inside 14 days of expiring is marked with the number of days it has left.

Revoked and expired secrets stay in the list for 30 days and then drop off it. The secrets themselves are already unusable by then.

You can issue a secret at the same time you create a service account. Simply enable the Generate a secret option.

Generate secret is available only while the service account has no live secret. Once it has one, add the second through Rotate.

Exchange a secret for an access token​

Your application sends the client ID and secret to the token endpoint and receives an access token in return.

Read the token endpoint from the OpenID Connect discovery document rather than hard-coding it. The same code then works against Seqera Cloud and any Enterprise installation:

curl --silent 'https://cloud.seqera.io/api/.well-known/openid-configuration' | jq -r '.token_endpoint'

Exchange the credentials for an access token at that endpoint, sending them in an Authorization: Basic header as base64(client_id:client_secret):

curl --request POST \
  --url "$TOKEN_ENDPOINT" \
  --user 'sa_EXAMPLECLIENTID:EXAMPLESECRET' \
  --data 'grant_type=client_credentials'

The response carries the access token and its lifetime in seconds:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Send that token as a bearer token on your API requests, the same way you would a personal access token.

A few things to design around:

  • The access token lasts one hour by default. Exchange the secret again when it expires. Build the exchange into your application rather than fetching a token by hand.
  • There is no refresh token. The client_credentials grant does not issue one. Re-exchange the secret instead.
  • You cannot narrow the token's access. A requested scope is ignored. The token carries the service account's own permissions, in full.
  • You can also send the credentials in the request body, as client_id and client_secret form fields. If you send both, the request is rejected as a client must not use more than one authentication method (RFC 6749 §2.3.1). Sending the same credentials two ways is a common source of confusing failures — pick one.

Rotate a secret​

Rotating means standing up a second secret before you retire the first, so your application never loses access.

  1. From the Service accounts tab, select the service account.
  2. Under Client credentials, select Rotate on the live secret.
  3. Choose an expiry and generate the new secret.
  4. Copy the new secret and deploy it to your application.
  5. Confirm the application is using it. The Last used column shows when each secret was last exchanged.
  6. Revoke the old secret.

Both secrets authenticate independently while both are live, so there is no window where your application is locked out.

Because a service account holds at most two live secrets, Rotate is unavailable while two are already live. Revoke one before rotating again.

Revoke a secret​

  1. From the Service accounts tab, select the service account.
  2. Under Client credentials, find the secret.
  3. Select Revoke.
  4. Confirm.

Revoking cannot be undone. Revoking a secret that is already revoked changes nothing. You cannot revoke a secret that has already expired — expiry is final, and Platform rejects the attempt.

caution

Revoking a secret stops it being exchanged for new access tokens immediately. It does not invalidate access tokens already issued from it. Those remain valid until they expire, which is up to an hour.

Treat revocation as "no further tokens" rather than "access has stopped". If you need the application to stop acting now, remove the service account's workspace access or delete the service account as well. See Service account security.

What the access token can do​

An access token carries exactly the permissions of the service account it belongs to — nothing added, nothing removed. It can act only where the service account has been assigned a workspace role. See Assign a service account to a workspace.

Permissions are read when the token is issued. If you change the service account's role, the change applies to the next token your application exchanges, not to one it already holds.

Platform refuses to issue a token if the service account has been deleted, or if client credentials are not enabled for its organization. Credentials work independently of agents — an organization that does not use agents can still use them.

On this Page