Skip to main content

​
Authentication

Every call to the KOSTRA REST API is authenticated with a token that represents a user. You obtain the token once from the authentication service, then present it on each request.

​
Obtain a token

Exchange a user’s credentials for a token by posting to the authentication service.
A successful response returns a token string along with its associated user and organization context. Treat the token as a secret: it carries the permissions of the user it represents.

​
Authenticate requests

Present the token on every REST API call using the x-optscale-token header.
The same header is used for all endpoints in this reference. A request without a valid token receives a 401 response.

​
Token lifetime and rotation

Tokens are time-limited. When a token expires, request a new one with the same flow. For automated integrations, obtain a token at the start of a run and refresh it if a long-running job outlives the token’s validity. Do not embed long-lived credentials in client code; store the user credentials securely and mint tokens as needed.

​
Service accounts for automation

For unattended integrations — a nightly export, a chargeback pull, a CI step — use a dedicated user with a role scoped to exactly what the integration needs, rather than a person’s interactive account. This keeps automated access auditable and easy to revoke, and ensures the integration’s permissions match its purpose.

​
A minimal example

The typical sequence for any script is:
  1. POST /auth/v2/tokens with the service user’s credentials to obtain a token.
  2. Call the REST API with x-optscale-token: <token> on each request.
  3. Refresh the token if it expires during a long run.
Adjust the host to your own KOSTRA instance.