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
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:
Make sure the Service Account is bound to the target workspace, then pass the full SA Key in the Bearer header:
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.
If you need a short-lived token, use the SA Key configured above to call the Service Token Exchange endpoint:
The
If your server-side integration needs to call both Forward (
The same SAT can call both API families:
For Managed APIs, pass a PAT, SA Key, or SAT as a bearer credential. For Forward APIs, use a PAT or SAT:
Set the selected credential as a common environment variable:
Full request example:
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).
| Credential | Use case | How to obtain it |
|---|---|---|
| PAT | User identity; suited to personal development and testing | Create it in the Qoder console |
| SA Key | Service Account identity for direct Managed API calls; suited to server-side integrations and automation | Create it on the Service Account details page in the Qoder admin console |
| SAT | Service Account identity for integrations that need short-lived tokens or access to both Forward and Managed APIs | Exchange 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:
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:
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
- 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. If you choose to exchange it for an SAT, specify scopes in the exchange request.
- Copy the SA Key and set it as an environment variable:
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:
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:
| 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) |
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:
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.
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:
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.