Authentication

Audience

This API surface is for integration partners building on top of the Rokt network. Rokt ecommerce partners integrating placements on their own checkout should use the Rokt Ecommerce developer docs instead.

Every call to the Partnerships API is authenticated with a short-lived access token passed as a bearer credential, plus your partner platform's parent account ID in an X-Platform-Parent-Account-Id header on writes. You obtain the access token by exchanging your long-lived API credentials (client_id + client_secret) at the Rokt auth endpoint.

Authorization: Bearer <access-token>
X-Platform-Parent-Account-Id: <your-platform-parent-account-id>

Get an access token

Access-token acquisition is a two-step flow:

1. Get API credentials (one-time). A client_id + client_secret pair is provisioned for your platform. Issuance is currently white-glove — email smb-partnerships@rokt.com with your platform name, expected merchant volume, and the manager account ID you've been assigned. Self-serve issuance is on the roadmap.
2. Exchange API credentials for an access token (every ~5 minutes). POST the credentials to the Rokt auth endpoint to get a short-lived JWT access token. Use that access token as the Authorization: Bearer value on every Partnerships API call.

警告

Treat client_secret like a password — store it in a secret manager, never check it into source, never expose it to a browser. Only the short-lived access token should travel to anything Partnerships-API-adjacent.

Exchange API credentials for an access token

curl -X POST 'https://auth.rokt.com/api/v1/oauth/token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=rspub_xxxxxxxxxxxx' \
  --data-urlencode 'client_secret=rsec_xxxxxxxxxxxx'

Standard OAuth2 client-credentials response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300
}

Pass access_token as Authorization: Bearer <access_token> on every Partnerships API call. expires_in is in seconds — roughly 5 minutes.

Headers on every call

Authorizationstringrequired

Bearer <access-token>. Required on every endpoint.

X-Platform-Parent-Account-Idstringrequired

Required on every write (POST / PUT) call. Set to your partner platform's Rokt parent account ID — the same value you pass in the platform_parent_account_id body field on register. Missing it on a write returns 422. Mismatched against the managed account's actual parent returns 403. Reads accept the header as optional; recommended on every call for clarity.

Idempotency-Keyuuidrequired

Required on every write (POST/PUT) call. UUID format, 24-hour dedup window. See Idempotency.

X-Request-Idstring

Optional correlation ID. Pass your own value if you want it threaded through Rokt's server logs and the response envelope — useful when correlating your own logs against support tickets. If omitted, Rokt generates one and returns it in request_id on the response envelope.

Example request

curl

curl -i 'https://accounts.rokt.com/v1/partnership/accounts?parent_account_id=<your-platform-parent-account-id>' \
  -H "Authorization: Bearer <access-token>" \
  -H "X-Platform-Parent-Account-Id: <your-platform-parent-account-id>" \
  -H "X-Request-Id: 8f3a9c2b-1d4e-4f5a-9b6c-2e8d7a1f3b5c"

The list endpoint requires ?parent_account_id=<your-parent-id>. A consolidated single-account GET /v1/partnership/accounts/{id} is not yet exposed — use the per-resource reads (marketplacecontrolslists, status) instead.

401 vs 403 vs 422

The three errors mean different things. Don't conflate them.

Status	Meaning	What to do
401 Unauthorized	The access token is missing, expired, malformed, or its signature doesn't validate.	Refresh by re-exchanging your API credentials. If the failure persists, your token-issuance integration is misconfigured.
403 Forbidden	The access token is valid, but either (a) you don't have permission to act on that account on behalf of your manager — your platform's account-to-account grant config is missing or hasn't synced — or (b) the X-Platform-Parent-Account-Id you sent doesn't match the managed account's actual parent.	Check that the account_id belongs to your manager and the header value is correct. If you believe both are right, file a support ticket with the request_id from the envelope.
422 Unprocessable	A required header is missing on a write. Most commonly X-Platform-Parent-Account-Id.	Add the header and retry with the same Idempotency-Key.

Access token rotation

Access tokens are short-TTL — roughly 5 minutes. Your client should refresh on each request, or cache and refresh on expiry. Do not hard-code access tokens, and never embed the long-lived client_secret in client-side code. Access tokens are JWTs, so you can decode them client-side to inspect the exp claim while debugging expiry issues; nothing else in the access token is part of the partner contract.

If a long-running batch job sees 401 mid-batch, re-exchange your API credentials for a fresh access token and retry. With Idempotency-Key the retry collapses to a no-op for any write that already succeeded inside the 24-hour dedup window.

Rate limits

Your API credentials key your per-minute request quota on write-heavy endpoints. Every server in your fleet using the same client_id shares one bucket. See Rate Limits for per-endpoint caps and the 429 envelope.