Exchange a client credential for a short-lived access token

OAuth 2.0 client credentials grant (RFC 6749 section 4.4). Authenticate with HTTP Basic (client_secret_basic) or with client_id and client_secret in the form (client_secret_post). Without `resource` the token is a Platform token for the Vision Core API. With `resource` set to an App's token audience (for example `vision-crm-live`), the token is for that App: the key must be bound to the App, made on this tier, and every requested scope must be granted to the key and catalogued for the App as allowed for client credentials (To-Do's https-origin `resource` is the one exception: granted and catalogued for To-Do); anything else is `invalid_target` or `invalid_scope`. With a module audience `resource`, an `app_service` client may name another business on its installation with `workspace_id`; the token then names that business. Tokens are JWTs signed with a key from /.well-known/jwks.json and carry the claims in the AccessTokenClaims schema; there is no refresh token. Keys are bound to the tier they are made on (`environment` claim): a preview key cannot mint a live token.

App

Vision Core

Contract

Platform API 1.0.0-preview.8

Lifecycle

preview

Runtime

acceptance-gated

Operation ID

exchangeClientCredentials

Canonical origin

https://app.runonvision.com

Purpose and use cases

Exchange a client credential for a short-lived access token

The owning App is Vision Core. Vision owns machine identity and common API policy. Source Apps retain their resource and business authority.

Request

POST https://app.runonvision.com/oauth/token

Authentication and authorization

No authentication requirement is declared for this operation.

Headers

• Accept: application/json — recommended where a JSON response is declared.
• Content-Type: application/x-www-form-urlencoded — required for the documented request representation.

Undeclared tracing, idempotency, conditional-request, and version headers are not assumed on this page.

Path and query parameters

This operation declares no path or query parameters.

Request body

Media type: application/x-www-form-urlencoded. The body is required.

Runnable examples

curl 'https://app.runonvision.com/oauth/token' \
  --request POST \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'client_secret=<client_secret>' \
  --data-urlencode 'scope=<scope>' \
  --data-urlencode 'resource=<resource>' \
  --data-urlencode 'workspace_id=00000000-0000-4000-8000-000000000001'

const response = await fetch('https://app.runonvision.com/oauth/token', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
  "grant_type": "client_credentials",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "scope": "<scope>",
  "resource": "<resource>",
  "workspace_id": "00000000-0000-4000-8000-000000000001"
}),
}

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()

import json
import urllib.parse
import urllib.request

request = urllib.request.Request(
    'https://app.runonvision.com/oauth/token',
    data=urllib.parse.urlencode({"grant_type":"client_credentials","client_id":"<client_id>","client_secret":"<client_secret>","scope":"<scope>","resource":"<resource>","workspace_id":"00000000-0000-4000-8000-000000000001"}).encode(),
    headers={
    "Accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

The current TypeScript reference client covers Platform token exchange and core reads. No native SDK helper is declared for this operation; use the HTTP contract directly and follow the SDK guidance.

Responses

Success response schema

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 60,
  "scope": "<scope>"
}

Errors and troubleshooting

Error bodies and codes are shown only where the approved contract declares them. Use status, the declared error schema, and any correlation identifier returned by the App; do not infer that two Apps share one envelope.

• 400 — `invalid_request` (not form-encoded), `unsupported_grant_type` (anything but client_credentials), `invalid_scope` (scope not granted to the key or not allowed for the App) or `invalid_target` (resource unknown, not bound to the key, App not active, or key made on another tier).
• 401 — Client authentication failed (invalid_client, RFC 6749 section 5.2)
• 429 — Rate limited (429) or temporarily unavailable (503); retry after the given delay
• 503 — Rate limited (429) or temporarily unavailable (503); retry after the given delay

Collection behavior

Pagination: not declared. Filtering/search: not declared. Sorting: not declared.

Cursor lifetime, cursor binding, stable ordering, maximum traversal, and unknown-filter behavior are not assumed unless stated by a parameter description or schema constraint above.

Operational behavior

• Rate limit: The operation declares 429, but the numeric policy is not in OpenAPI.
• Retry: Retry only when the documented error model or response headers authorize it. Timeout and backoff values are not declared by this operation.
• Idempotency: No idempotency header or replay window is declared.
• Concurrency: No ETag, If-Match, or optimistic-version header is declared.

Security and privacy

• Keep client credentials and bearer tokens on trusted servers.
• Send only to the exact approved HTTPS origin and audience.
• Treat response data according to the owning App's classification and retention policy; the OpenAPI contract does not itself grant data access.
• Do not log credentials, tokens, complete private payloads, or secrets.

Edge cases and known documentation gaps

• The request body has no purpose or conditional-rule description.
• Business roles, timeout, retry budget, rate value, idempotency window, and concurrency behavior are absent unless explicitly stated above.

Related operations and workflows

No related operation is identified by the contract tags.

Contract history and evidence

• Contract version: 1.0.0-preview.8
• Approved snapshot SHA-256: e696d48690f5bd5983b044fb77eff04f29d112a51fe150409c1542386d1b74d3
• Approval: Anthony, 2026-11-03T01:23:27.515Z (anthony-docs-live-20261102)
• Download the authoritative OpenAPI 3.1 snapshot