Skip to content
Stackship documentation Svenska

Stackship platformUsers

Authenticate

Get an access token as a person or as a service account, and send it with your API calls.

The API accepts OAuth 2.0 access tokens issued by the platform's identity provider, https://auth.example.com, realm stackship. Send the token in the Authorization header of every call:

http
GET https://api.example.com/boundaries
Authorization: Bearer <access-token>

As a person, with the CLI

People sign in interactively in a browser; the platform offers no password grant. The stsh CLI does this for you:

  1. Run stsh setup once. It asks for the Platform API URL (https://api.example.com), the Keycloak URL (https://auth.example.com) and the Keycloak realm (stackship); keep the defaults for the client id and the audience.
  2. Run stsh login. It opens your browser, you sign in as you do in the portal, and the CLI keeps the tokens and refreshes them.
  3. Check who you are signed in as:
bash
stsh whoami

From then on every stsh command, including stsh api, calls the API as you.

As a service account

Scripts and pipelines should sign in as a service account. A service account uses the client credentials grant against the identity provider's token endpoint:

bash
TOKEN=$(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" | jq -r .access_token)

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/boundaries

No scope or audience parameter is needed. Tokens are short-lived — fifteen minutes unless your platform is configured otherwise — so request a new one when a call answers 401.

Tokens for the CLI in automation

The CLI reads credentials from its environment before it looks at a stored login:

Variable Effect
STACKSHIP_TOKEN Used as the bearer token as it is
STACKSHIP_CLIENT_ID and STACKSHIP_CLIENT_SECRET The CLI gets a token for that service account; the context still needs the Keycloak URL and realm from stsh setup

The first one set wins, in the order of the table; without either, the CLI uses the stored login.

What the API checks

A token is accepted when it:

  • was issued by https://auth.example.com/realms/stackship and its signature verifies;
  • has not expired;
  • carries the audience stackship-kubernetes-client — tokens from the portal, the CLI and service accounts do;
  • is an access token — ID tokens are refused.

Otherwise the call answers 401. A token proves who you are; what you may do is decided by your roles at the scope the route names, and a call you lack the permission for answers 403. See Errors.