Service account authentication

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

You must migrate all your workflows to the Key flow by December 17, 2025, as the Token flow will be removed from the platform on that date.

Key flow (Recommended)

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. Here’s a step-by-step breakdown of how it works:

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

The short lifespan of these tokens is a critical security feature, as it drastically minimizes the opportunity for an attacker to use a compromised token.

Setting up the Key flow

There are several methods you can use to configure a service account key for authentication, depending on the tool you’re using.

Refer to the authentication section for the Developer Tool your interested in.

Refer to the guide Aquire 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 authentication 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 security issue with the Token flow is its 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 unauthorized access for its entire lifespan, greatly increasing the impact of a single credential compromise. Due to these risks, STACKIT has scheduled the removal of the Token flow.