Service account authentication

STACKIT Cloud uses two main authentication methods: key flow and token flow. Key flow is the recommended and more secure method. Token flow is an older, deprecated method.

You must migrate all workflows to the key flow by 17 December 2025, as the token flow will be removed on that date.

Federated identity flow (recommended)

The federated identity flow is a recommended and secure method that allows a service account to authenticate using short‑lived tokens acquired from an external OIDC issuer. You can acquire short‑lived tokens without static keys.

How it works

Link your service account to an external OIDC issuer by configuring a federated identity provider. Tokens from the external issuer are accepted only when the issuer URL matches and all assertion conditions are met.

1. Your external system (for example, a CI/CD pipeline) generates an OIDC token from the trusted external issuer.
2. Your application presents this external token to STACKIT.
3. STACKIT validates the token against the configured issuer URL and assertions (for example, checking if the subject EQUALS a specific value).
4. After successful verification, STACKIT issues a short‑lived access token to your application, which it uses as a bearer token for API requests.

Set up the federated identity flow

Manage federated identity providers in the STACKIT Portal under IAM and Management > Service accounts. Define the provider name, the exact issuer URL, and the required assertions.

Key flow

The key flow is the recommended and more secure authentication method. It uses a cryptographic challenge–response mechanism based on a service account key and an RSA key pair to authenticate applications. This method uses short‑lived tokens, which significantly reduces security risks.

How it works

The key flow separates a long‑lived private key from the short‑lived access tokens used for API requests.

1. Your application (the client) uses its private RSA key to sign a JSON Web Token (JWT). The private key is kept secret and is never sent over the network.
2. The application sends the signed JWT to the STACKIT server to request a temporary access token.
3. The STACKIT server uses the corresponding public key to verify the authenticity and integrity of the JWT.
4. After successful verification, the STACKIT server issues a short‑lived access token.
5. Your application uses the temporary access token as a bearer token for API requests until it expires. After expiry, request a new token by repeating the JWT exchange.

Short token lifespans minimise the opportunity for an attacker to use a compromised token.

Setting up the Key flow

Choose a method to configure a service account key, depending on your tool.

Refer to the authentication section for the Developer Tool you’re interested in.

Refer to the guide Acquire a bearer token to learn about the prerequisites and how to obtain a short-lived token.

Token flow (deprecated)

The token flow is a legacy method that is less secure than the key flow. It uses a single, long‑lived service account token directly as a bearer token for all requests.

Security risks

The main risk is the use of long‑lived, static tokens. These tokens cannot be revoked once issued. If a token is compromised, a malicious actor can use it to gain unauthorised access for its entire lifespan, greatly increasing the impact of a single credential compromise. Due to these risks, STACKIT will remove the token