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.

Authenticating to the Partnerships API requires two sets of credentials:

• API credentials: a long-lived client_id and client_secret that Rokt issues to your platform once, during onboarding; you don't generate them. If you don't have them yet, see Get your API credentials.
• JWT access token: a short-lived token you create by sending your API credentials to Rokt's auth endpoint. See Exchange API credentials for an access token to learn how.

The access token is what authorizes your calls to the Partnerships API. Include it in the Authorization header on every request. On writes, also send your platform's parent account ID:

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

Get your API credentials

Rokt grants your initial credentials

You can't generate your own Partnerships API credentials. They must be issued to your platform by Rokt during your onboarding. These API credentials are long-lived and reusable: you use the same set of credentials to generate your temporary access tokens.

To request your API credentials, email smb-partnerships@rokt.com with:

• Your platform name.
• Your expected merchant volume.
• The manager account ID you've been assigned.

Rokt responds with your platform's client_id and client_secret, which you use for every access-token exchange. You request them only once; a self-serve option is coming in a future release.

warning

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

POST the credentials to the Rokt auth endpoint to get a short-lived JWT access token; you repeat this roughly every 5 minutes as tokens expire. Use the access token as the Authorization: Bearer value on every Partnerships API call.

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.