Skip to main content

Authentication

Authenticate Qoder Cloud Agents API requests with a PAT, Service Account API Key (SA Key), or SAT.

The Qoder Cloud Agents API authenticates requests through Authorization: Bearer <credential>. Personal users use a Personal Access Token (PAT). Service Accounts can call Managed APIs directly with a Service Account API Key (SA Key), or use a Service Account Token (SAT).
CredentialUse caseHow to obtain it
PATUser identity; suited to personal development and testingCreate it in the Qoder console
SA KeyService Account identity for direct Managed API calls; suited to server-side integrations and automationCreate it on the Service Account details page in the Qoder admin console
SATService Account identity for integrations that need short-lived tokens or access to both Forward and Managed APIsExchange an SA Key for a short-lived JWT, or issue a token through the Forward token APIs
For Managed APIs (/api/v1/cloud/*), pass the full SA Key in the Bearer header without first exchanging it for an SAT. Service Account integrations that call Forward APIs should use the SAT flow below.

Select a service region

Choose API endpoints in the same region as your account, credentials, and resources. If you use an SAT, the 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

  1. Sign in to the Qoder console.
  2. Open Settings → Personal Access Tokens.
  3. Click Create token and configure its name, scopes, and expiration.
  4. 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: Call Managed APIs directly with an SA Key

Obtain and configure an SA Key

  1. Sign in to the Qoder console as an organization administrator.
  2. Create or select a Service Account under organization management.
  3. Create an API Key from the Service Account details page. You do not select scopes when creating the key. If you choose to exchange it for an SAT, specify scopes in the exchange request.
  4. Copy the SA Key and set it as an environment variable:
export QODER_SA_KEY="your-service-account-api-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.

Call Managed APIs directly

Make sure the Service Account is bound to the target workspace, then pass the full SA Key in the Bearer header:
curl -s "$QODER_API_BASE_URL/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_SA_KEY"
Your client does not need to call the token exchange endpoint or renew SATs. Requests still use the Service Account identity, and resource access remains subject to its permissions and workspace binding. See Personal and enterprise spaces for the console setup.

Option 3: Use an SAT (optional)

Exchange the SA Key for an SAT (JWT)

If you need a short-lived token, use the SA Key configured above to call the Service Token Exchange endpoint:
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')"
FieldDescription
grant_typeMust be client_credentials
audienceMust be qoder
scopeSpecify 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_secondsSAT 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

For Managed APIs, pass a PAT, SA Key, or SAT as a bearer credential. For Forward APIs, use a PAT or SAT:
Authorization: Bearer <PAT, SA Key, or SAT>
Set the selected credential as a common environment variable:
# Personal user
export QODER_ACCESS_TOKEN="$QODER_PAT"

# Or Service Account calling Managed APIs directly
export QODER_ACCESS_TOKEN="$QODER_SA_KEY"

# Or an SAT obtained earlier
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.
  • If you use an SAT, exchange a replacement before it expires and rotate it safely in the running service. Direct SA Key calls do not require SAT renewal.
  • Revoke or rotate any leaked PAT or SA Key immediately in the console.