Get OAuth2 Access Token

GET /v1/secrets/:id/oauth2/token

For OAuth2-type secrets, returns the current access token. If the token has expired, KnoxCall will automatically refresh it before returning.

Required scope

secrets:oauth_token (or secrets:*). This endpoint returns a live upstream credential and refreshes it at the provider, so it is deliberately not covered by secrets:read, whose scope is secret metadata. If you authenticate with an OAuth access token that was deliberately narrowed, its grant must include secrets:oauth_token; a token narrowed to secrets:read receives 403 insufficient_scope and the WWW-Authenticate header names the scope to request. API keys (tk_/AKE) and key-mirrored OAuth clients carry no scope grant and are unaffected. Changed 2026-08-26 — see the changelog.

Path Parameters

Parameter	Type	Description
`id`	uuid	The secret ID (must be an OAuth2-type secret)

Query Parameters

Parameter	Type	Default	Description
`environment`	string	Base environment	Target a specific environment

Response

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "expires_at": "2026-03-10T15:30:00.000Z",
    "token_type": "Bearer",
    "connection_status": "connected"
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Errors

Status	Type	Description
400	`invalid_type`	Secret is not an OAuth2 type
403	`insufficient_scope`	The access token’s scope grant does not include `secrets:oauth_token`
404	`not_found`	Secret not found
500	`token_error`	Failed to retrieve or refresh the OAuth2 token

Overview

Workload Identity

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Get OAuth2 Access Token