> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kostra.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Obtain a KOSTRA API token and authenticate REST calls with the x-optscale-token header.

# 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.

```bash theme={null}
# 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.

## Related pages

* [API Reference](/api/index)
* [Data Sources API](/api/data-sources)
* [Security & Data Protection](/security-and-data-protection)