Resolve a credential

Resolve an OAuth, API-key, or basic-auth credential at runtime. Used by the agent's task to obtain the secret value just before it makes a request to a third-party API.

Endpoint

GET /api/credentials/{connectionId}/resolve

Auth: Two factors are required.

Authorization: Bearer <agent_api_key>
X-Credentials-Token: <credentials_jwt>

Where each value comes from inside a task:

Value	Source
`connectionId`	`payload.connectionIds['<integration_id>'].connectionId` in the task payload.
`agent_api_key`	Environment variable on the runtime environment (not in the per-run payload).
`credentialsToken`	`payload.credentialsToken` in the task payload, or the response of `/runs/register`.

The credentials JWT is bound to (agentId, runId) with a 60-minute TTL.

Response variants

The body is a discriminated union on type.

API key

json

{
  "type": "api_key",
  "value": "sk_live_…",
  "extras": { "region": "eu-west-1" }
}

Basic auth

json

{
  "type": "basic_auth",
  "username": "alice",
  "password": "p@ssw0rd",
  "extras": {}
}

OAuth

json

{
  "type": "oauth",
  "access_token": "ya29.…",
  "extras": {
    "token_type": "Bearer",
    "expires_at": "2026-03-15T13:00:00Z",
    "scope": "read:items"
  }
}

The extras object merges fields from the OAuth provider with admin-supplied connection metadata; admin metadata wins on collision.

Errors

Status	Reason
`401`	Missing/invalid agent key, or missing/expired credentials token.
`403`	The credentials token is bound to a different agent or run.
`404`	`connectionId` not found or not visible to this agent.
`502`	Upstream OAuth provider refused to return the token.

SDK

const cred = await cxpa.resolveCredential(connectionId)
if (cred.type === 'oauth') {
  await fetch(url, {
    headers: { authorization: `Bearer ${cred.access_token}` },
  })
}