Skip to content
Stackship documentation Svenska

Stackship platformUsers

Service accounts

Create a service account for CI/CD or another integration, give it roles, get a token with its credentials, and rotate or delete it.

Requires: rbac/members/write

A service account is a principal for a machine rather than a person — a CI/CD pipeline, a script, another system. It signs in with a client ID and a client secret instead of a password, and it can do exactly what the roles assigned to it allow.

Creating, rotating and deleting service accounts needs rbac/members/write on the boundary; Owner and Platform Owner have it. Listing them needs rbac/members/read.

Create a service account

  1. Open Settings → Identity in the sidebar, then the Service Accounts tab. Check that the boundary selected in the sidebar is the one the account is for.
  2. Choose Create.
  3. Enter a Name, for example CI/CD Pipeline, and, if you like, a Description (optional).
  4. Create the account. The Credentials dialog shows its Client ID and Client Secret.
  5. Copy both and store them where the system that will use them keeps its secrets — for example a vault or your CI system's secret store. Then choose Done.

Important

The client secret is shown only once. If it is lost, rotate the secret to get a new one.

The client ID has the form sa- followed by a generated identifier; the name you entered is only the account's display name. The Service Accounts tab also lists managed identities — the identities the platform creates for workloads; use the type filter to tell them apart.

With the CLI:

bash
stsh iam sa create --set name=ci-pipeline --set description="Deploys from CI"

Give it roles

A new service account holds no roles and can do nothing. Assign it roles like any other principal: in Access control (IAM), choose Add role assignment, search for the service account by its name, and pick the role and scope — see Assign a role. Grant only what the integration needs, at the narrowest scope that works.

Get a token

A service account gets an access token from the platform's identity provider with the OAuth 2.0 client credentials grant, and sends it to the API as a bearer token:

bash
curl -s https://auth.example.com/realms/stackship/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"

Use the access_token from the response as Authorization: Bearer <token> on calls to https://api.example.com. Tokens are short-lived — fifteen minutes unless your platform is configured otherwise — so fetch a new one when it expires. See Authenticate.

The stsh CLI signs in as a service account when STACKSHIP_CLIENT_ID and STACKSHIP_CLIENT_SECRET are set in its environment:

bash
export STACKSHIP_CLIENT_ID=sa-...
export STACKSHIP_CLIENT_SECRET=...
stsh whoami

The CLI context still needs the identity provider's address and realm, which stsh setup asks for.

Rotate the secret

Choose Rotate secret on the account's row and confirm. The new secret is shown once. The previous secret stops working immediately; tokens already issued with it stay valid until they expire.

bash
stsh iam sa rotate-secret <service-account-id>

Delete a service account

Choose the delete action on the account's row and confirm Delete service account?. Every system using the account loses access as soon as its current token expires.

Deleting the account does not remove its role assignments. Remove them in Access control (IAM) as well.

bash
stsh iam sa delete <service-account-id>