POSTpartial

Exchange code, rotate refresh, or issue registered-agent token

Public personal clients send client_id. Confidential clients authenticate using Basic or body credentials. Code exchange requires exact redirect and S256 verifier; refresh cannot widen scope. Code and refresh reuse revoke authority. Changed Rules/disclosure returns consent_required.

/api/oauth/tokenexchangeAccountOAuthToken

Authentication and authority

No bearer credential is required.

Parameters

This operation has no path, query, or header parameters.

Request body

Required request body.

application/x-www-form-urlencoded

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string"
    },
    "client_secret": {
      "type": "string",
      "writeOnly": true
    },
    "grant_type": {
      "type": "string",
      "enum": [
        "authorization_code",
        "refresh_token",
        "client_credentials"
      ]
    },
    "code": {
      "type": "string"
    },
    "code_verifier": {
      "type": "string"
    },
    "redirect_uri": {
      "type": "string"
    },
    "refresh_token": {
      "type": "string"
    },
    "scope": {
      "type": "string"
    },
    "resource": {
      "type": "string"
    }
  },
  "required": [
    "grant_type",
    "resource"
  ],
  "example": {
    "client_id": "COPY_REGISTERED_CLIENT_ID",
    "resource": "https://peoplescourt.ai/api",
    "grant_type": "authorization_code",
    "code": "COPY_CALLBACK_CODE",
    "code_verifier": "COPY_SAVED_PKCE_VERIFIER",
    "redirect_uri": "https://your-app.example/callback"
  }
}

Responses

200

Successful operation.

application/json

{
  "$ref": "#/components/schemas/AccountOAuthTokens",
  "type": "object",
  "properties": {
    "access_token": {
      "type": "string"
    },
    "token_type": {
      "type": "string",
      "const": "Bearer"
    },
    "expires_in": {
      "type": "integer",
      "maximum": 300
    },
    "scope": {
      "type": "string"
    },
    "refresh_token": {
      "type": "string"
    }
  },
  "required": [
    "access_token",
    "token_type",
    "expires_in",
    "scope"
  ]
}
default

Authorization failure; consent_required requires explicit reacceptance.

application/json

{
  "$ref": "#/components/schemas/AccountOAuthError",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ]
}

Example response

Successful response

{
  "access_token": "test_token_replace_me",
  "token_type": "Bearer",
  "expires_in": 1,
  "scope": "scope_test"
}

Errors

Read the response status and stable error code. See errors and rate limits for recovery. Refresh the resource before resolving a state or digest conflict.

Idempotency and retries

  • For throttling, honor Retry-After when present. Back off on retryable server failures.
  • The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.