Copy

The Qoder Cloud Agents API accepts two types of bearer tokens: Personal Access Tokens (PATs) and Service Account Tokens (SATs). Every API request must include one valid token in the Authorization header.

Token	Use case	How to obtain it
PAT	User identity; suited to personal development and testing	Create it in the Qoder console
SAT	Service Account identity; suited to server-side integrations and automation	Exchange a Service Account API Key (SA Key) for a short-lived JWT

An SA Key is a long-lived credential used to exchange for an SAT. Do not use the SA Key directly to call Cloud Agents business APIs.

Select a service region

The SAT exchange and business API requests must use endpoints in the same region. Set the following service endpoints:

export QODER_OPENAPI_BASE_URL="https://openapi.qoder.sh"
export QODER_API_BASE_URL="https://api.qoder.com"

Option 1: Use a PAT

Obtain a PAT

Sign in to the Qoder console.
Open Settings → Personal Access Tokens.
Click Create token and configure its name, scopes, and expiration.
Copy the PAT and set it as an environment variable:

export QODER_PAT="pt-your-token-here"

PATs are prefixed with pt-, and the full value is shown only once at creation. Never commit a token to source control or share it.

Option 2: Use a Service Account and SAT

Obtain and configure an SA Key

Sign in to the Qoder console as an organization administrator.
Create or select a Service Account under organization management.
Create an API Key from the Service Account details page. You do not select scopes when creating the key; specify the required scopes later when exchanging it for an SAT.
Copy the SA Key and set it as an environment variable:

export QODER_SA_KEY="sa-key"

The full SA Key is shown only once at creation. Store it in a secrets manager; never put it in source code or logs.

Exchange the SA Key for an SAT (JWT)

Call the Service Token Exchange endpoint to exchange the SA Key for an SAT:

SAT_RESPONSE=$(curl --silent --show-error --location "$QODER_OPENAPI_BASE_URL/api/v1/serviceToken/exchange" \
  --header "Authorization: Bearer $QODER_SA_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "audience": "qoder",
    "scope": "qca.access",
    "ttl_seconds": 43200
  }')

export QODER_SAT="$(printf '%s' "$SAT_RESPONSE" | jq -r '.access_token')"

Field	Description
`grant_type`	Must be `client_credentials`
`audience`	Must be `qoder`
`scope`	Specify it in the exchange request: use `qca.access` for Managed APIs only, or `qca.access forward.access` for both Forward and Managed APIs. It must not exceed the permissions configured for the SA Key
`ttl_seconds`	SAT lifetime in seconds; the maximum is `43200` (12 hours)

The access_token in the response is the SAT. An expired SAT cannot be refreshed; use the SA Key to call the exchange endpoint again.

Use one SAT for Forward and Managed APIs

If your server-side integration needs to call both Forward (/api/v1/forward/*) and Managed (/api/v1/cloud/*) APIs with the same SAT, request both qca.access and forward.access during the exchange:

SAT_RESPONSE=$(curl --silent --show-error --location "$QODER_OPENAPI_BASE_URL/api/v1/serviceToken/exchange" \
  -H "Authorization: Bearer $QODER_SA_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "audience": "qoder",
    "scope": "qca.access forward.access",
    "ttl_seconds": 3600
  }')

export QODER_SAT="$(printf '%s' "$SAT_RESPONSE" | jq -r '.access_token')"

An SAT containing both qca.access and forward.access has administrator access to Forward resources under the account associated with the Service Account. Use it only in trusted server-side environments. Do not provide it to end users or untrusted clients. Use separate SA Keys for each environment and choose the shortest lifetime that meets your needs.

The same SAT can call both API families:

# Forward API
curl -s "$QODER_API_BASE_URL/api/v1/forward/templates?limit=1" \
  -H "Authorization: Bearer $QODER_SAT"

# Managed API
curl -s "$QODER_API_BASE_URL/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_SAT"

Compatibility with existing integrations

Existing Managed-only integrations can continue to request and use only qca.access.
PAT acquisition and usage remain unchanged.
For Forward-only access, precise revocation, or an SAT bound to a single Identity, you can continue to use the Forward token APIs.

See the ServiceAccountTokens API reference for details.

Bearer header format

Pass either a PAT or SAT to the Cloud Agents API as a bearer token:

Authorization: Bearer <PAT or SAT>

Set the selected token as a common environment variable:

# Personal user
export QODER_ACCESS_TOKEN="$QODER_PAT"

# Or Service Account
export QODER_ACCESS_TOKEN="$QODER_SAT"

Full request example:

curl -s "$QODER_API_BASE_URL/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Security recommendations

Use separate PATs or SA Keys for development, staging, and production.
Store PATs and SA Keys in a secrets manager instead of hard-coding them.
Request only the scopes required by the integration when exchanging an SAT.
Exchange a replacement SAT before the current one expires, then rotate it safely in the running service.
Revoke or rotate any leaked PAT or SA Key immediately in the console.

​Select a service region

​Option 1: Use a PAT

​Obtain a PAT

​Option 2: Use a Service Account and SAT

​Obtain and configure an SA Key

​Exchange the SA Key for an SAT (JWT)

​Use one SAT for Forward and Managed APIs

​Compatibility with existing integrations

​Bearer header format

​Security recommendations

Select a service region

Option 1: Use a PAT

Obtain a PAT

Option 2: Use a Service Account and SAT

Obtain and configure an SA Key

Exchange the SA Key for an SAT (JWT)

Use one SAT for Forward and Managed APIs

Compatibility with existing integrations

Bearer header format

Security recommendations