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. 
POST /auth/v2/tokens
Content-Type: application/json

{
  "email": "analyst@example.com",
  "password": "••••••••"
}
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. 
GET /restapi/v2/organizations
x-optscale-token: <your-token>
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.
# 1. Get a token
TOKEN=$(curl -s https://app.example.com/auth/v2/tokens \
  -H 'Content-Type: application/json' \
  -d '{"email":"svc@example.com","password":"••••••••"}' \
  | jq -r '.token')

# 2. Call the API
curl -s https://app.example.com/restapi/v2/organizations \
  -H "x-optscale-token: $TOKEN"
Adjust the host to your own KOSTRA instance.