Authentication

The API Gateway supports three authentication methods. Every request must supply credentials in one of the forms described below.

Session Token

The standard method for user-facing requests. Pass the session token obtained after logging in.

GET /gpu/api/v1/servers HTTP/1.1
Host: instance-api.bitdeer.ai
Authorization: $USER_TOKEN

curl https://instance-api.bitdeer.ai/gpu/api/v1/servers \
-H "Authorization: $USER_TOKEN"

Token lookup order (first non-empty value wins):

Priority	Source
1	Cookie `User-Token-V1`
2	Query parameter `token`
3	`Authorization` header
4	Cookie `OU-Token-V1`

The gateway validates the token against the SSO service. On success it extracts the user identity and signs an internal JWT that is forwarded to the backend service.

API Key (AK/SK Signature)

Used for programmatic access. Every request must carry three query parameters: access_key, nonce, and signature, with the header X-AUTH-TYPE: AK.

GET /gpu/api/v1/servers?access_key=AK_xxx&nonce=1748870400&signature=<HMAC_SHA256> HTTP/1.1
Host: instance-api.bitdeer.ai
X-AUTH-TYPE: AK

Signature algorithm

Collect all request parameters except access_key, nonce, and signature.
Sort the keys alphabetically and join them as key=value&key=value.
Append nonce and api_key to produce the signing message.
Compute HMAC-SHA256(api_secret, message).

message   = sorted_params + nonce + api_key
signature = HMAC-SHA256(api_secret, message)

The nonce must be a Unix timestamp in seconds. Requests with a timestamp more than 30 seconds from the server clock are rejected.

NONCE=$(date +%s)
# Compute $SIG from your params, nonce, and api_secret first, then:
curl "https://instance-api.bitdeer.ai/gpu/api/v1/servers?access_key=$AK&nonce=$NONCE&signature=$SIG" \
-H "X-AUTH-TYPE: AK"

Get your Access Key

Log in to Bitdeer AI Console.
Navigate to Account → API Keys and click Create API Key.
Copy both the Access Key and API Secret — the secret is only shown once.

STS Token (Temporary Security Token)

Short-lived credentials for delegated or cross-account access. Pass the token via the STS-Token header, cookie, or query parameter. The gateway detects it automatically and sets the auth type to STS_TOKEN.

GET /gpu/api/v1/servers HTTP/1.1
Host: instance-api.bitdeer.ai
STS-Token: $STS_TOKEN

curl https://instance-api.bitdeer.ai/gpu/api/v1/servers \
-H "STS-Token: $STS_TOKEN"

Token lookup order (first non-empty value wins):

Priority	Source
1	Cookie `STS-Token`
2	Query parameter `STS-Token`
3	`STS-Token` header

STS tokens are issued by the STS token service and carry a built-in expiry. An expired or invalid token returns 401 Unauthorized with error code ERR_STS_UNAUTHORIZED.

Unauthorized responses

All authentication failures return 401 Unauthorized — see Errors for the response body shape.

Error code	Cause
`ERR_UNAUTHORIZED`	Missing or invalid bearer token
`ERR_STS_UNAUTHORIZED`	Expired or invalid STS token
`ERR_AUTHTYPE`	Auth type not permitted for this endpoint
`ERR_SIGNATURE`	HMAC signature mismatch or expired nonce

Key handling best practices

Never commit credentials or bundle them into client-side code.
Load from environment variables or a secrets manager.
For AK/SK: use the current Unix timestamp as nonce on every request — values older than 30 seconds are rejected.
Rotate by creating a new key, deploying it, then revoking the old one.