OPopensea
Auth Endpoints

Exchange a scoped token for an access token

Changed on

Exchanges an opaque scoped token (personal access token) for a short-lived access token that satisfies WalletAuth on wallet-scoped endpoints. Send the returned accessToken as Authorization: Bearer <token>.

This is the credential path for headless callers that hold no signing key: the scoped token in the request body is the only credential, so no session cookie, wallet signature, or API key is required. The alternative is the OAuth 2.1 authorization-code flow described by the WalletAuth security scheme.

Failures are deliberately opaque. An unknown, revoked, rotated, or non-scoped subject token and a disabled integration all return the same 403 Token exchange is not available, so a 403 is not by itself evidence that the endpoint is unavailable.

post/api/v2/auth/tokens/exchange

Request

Request body

subjectTokenstring required

The opaque scoped token (personal access token) to exchange. A session JWT is not accepted.

subjectTokenType'ACCESS_TOKEN'

Type of the presented subject token

Response

Access token minted

accessTokenstring required

Bearer token to send as Authorization: Bearer <token>

expiresIninteger

Token lifetime in seconds, when the issuer reports one

scopestring

Space-delimited scopes on the minted token, when present

tokenScopesAuthScope[]

Scopes bound to the presented scoped token at mint time. Requests are authorized against these, not the full account scope set.

tokenTypestring required

Token type

Example response

{
  "tokenScopes": [
    "read:favorites"
  ],
  "tokenType": "Bearer"
}

Changes