Exchange an API key for an access token
Start here. Exchanges your CMS-issued API credential (client_id + perkss_sk_live_… secret) for a short-lived Bearer token via the OAuth 2.0 client-credentials grant (RFC 6749 §4.4). Send the fields as an application/x-www-form-urlencoded body, or pass the credential pair via HTTP Basic authentication instead — the form fields win when both are present. expires_in in the response reflects the actually minted lifetime (ttl_seconds clamped to [60, 86400]; default 86400 = 24h); cache the token and reuse it until then rather than exchanging per request. Every other /api/v1 endpoint expects it as Authorization: Bearer <access_token>. Unlike every other endpoint, deliberate failures here use the RFC 6749 §5.2 error shape, not the standard error envelope.
Authentication
RFC 6749 client_secret_basic: API key id/secret as username/password — an alternative to the token-exchange form fields (the form wins when both are present). Only POST /api/v1/auth/token accepts it.
Request
OAuth 2.0 grant type — only client_credentials is supported.
The API key secret (perkss_sk_live_…) shown exactly once at creation. May alternatively be sent via HTTP Basic authentication.
Requested token lifetime in seconds, clamped to [60, 86400]. Defaults to 86400 (24h). Use short TTLs for browser-bound tokens.
Response
RFC 6749 §5.1 token response.
The Bearer token for all other /api/v1 endpoints. An opaque credential — do not parse or persist beyond its lifetime.
Seconds until expiry — reflects the actually minted lifetime after the ttl_seconds clamp to [60, 86400].