Authentification

Audience

Cette surface d'API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt intégrant des placements sur leur propre processus de paiement devraient utiliser les documents développeur Rokt Ecommerce à la place.

L'authentification à l'API des Partenariats nécessite deux ensembles d'informations d'identification :

Informations d'identification API : un client_id et un client_secret à long terme que Rokt émet à votre plateforme une fois, lors de l'intégration ; vous ne les générez pas. Si vous ne les avez pas encore, consultez Obtenez vos informations d'identification API.
Jeton d'accès JWT : un jeton à court terme que vous créez en envoyant vos informations d'identification API au point de terminaison d'authentification de Rokt. Voir Échanger les informations d'identification API contre un jeton d'accès pour savoir comment.

Le jeton d'accès est ce qui autorise vos appels à l'API des Partenariats. Incluez-le dans l'en-tête Authorization à chaque requête. Lors des écritures, envoyez également l'ID de compte parent de votre plateforme :

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

Obtenez vos informations d'identification APILien direct vers Obtenez vos informations d'identification API

Rokt vous accorde vos informations d'identification initiales

Vous ne pouvez pas générer vos propres informations d'identification API des Partenariats. Elles doivent être émises à votre plateforme par Rokt lors de votre intégration. Ces informations d'identification API sont à long terme et réutilisables : vous utilisez le même ensemble d'informations d'identification pour générer vos jetons d'accès temporaires.

Pour demander vos informations d'identification API, envoyez un email à smb-partnerships@rokt.com avec :

Le nom de votre plateforme.
Votre volume marchand attendu.
L'ID de compte gestionnaire qui vous a été attribué.

Rokt répond avec le client_id et le client_secret de votre plateforme, que vous utilisez pour chaque échange de jeton d'accès. Vous les demandez une seule fois ; une option en libre-service est prévue dans une future version.

attention

Traitez client_secret comme un mot de passe : stockez-le dans un gestionnaire de secrets, ne le vérifiez jamais dans le code source, ne l'exposez jamais à un navigateur. Seul le jeton d'accès à court terme doit être transmis à tout ce qui est adjacent à l'API des Partenariats.

Échanger les informations d'identification API contre un jeton d'accèsLien direct vers Échanger les informations d'identification API contre un jeton d'accès

POSTez les informations d'identification au point de terminaison d'authentification de Rokt pour obtenir un jeton d'accès JWT à court terme ; vous répétez cela environ toutes les 5 minutes car les jetons expirent. Utilisez le jeton d'accès comme valeur Authorization: Bearer à chaque appel à l'API des Partenariats.

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'

Réponse standard OAuth2 client-credentials :

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

Passez access_token comme Authorization: Bearer <access_token> à chaque appel à l'API des Partenariats. expires_in est en secondes, environ 5 minutes.

En-têtes à chaque appelLien direct vers En-têtes à chaque appel

Authorizationstringrequired

Bearer <access-token>. Requis sur chaque point de terminaison.

X-Platform-Parent-Account-Idstringrequired

Requis sur chaque appel d'écriture (POST / PUT). Définissez-le sur l'ID de compte parent Rokt de votre plateforme partenaire, la même valeur que vous passez dans le champ de corps platform_parent_account_id lors de l'enregistrement. L'absence de celui-ci lors d'une écriture renvoie 422. Un décalage par rapport au parent réel du compte géré renvoie 403. Les lectures acceptent l'en-tête comme optionnel ; recommandé à chaque appel pour plus de clarté.

Idempotency-Keyuuidrequired

Requis sur chaque appel d'écriture (POST/PUT). Format UUID, fenêtre de déduplication de 24 heures. Voir Idempotency.

X-Request-Idstring

ID de corrélation optionnel. Passez votre propre valeur si vous souhaitez qu'elle soit transmise à travers les journaux de serveur de Rokt et l'enveloppe de réponse, utile lorsque vous corrélez vos propres journaux avec les tickets de support. Si omis, Rokt en génère un et le renvoie dans request_id sur l'enveloppe de réponse.

Exemple de requêteLien direct vers Exemple de requête

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"

L'endpoint de liste nécessite ?parent_account_id=<your-parent-id>. Un GET /v1/partnership/accounts/{id} consolidé pour un seul compte n'est pas encore exposé ; utilisez plutôt les lectures par ressource (marketplacecontrolslists, status).

401 vs 403 vs 422Lien direct vers 401 vs 403 vs 422

Les trois erreurs signifient des choses différentes. Ne les confondez pas.

Statut	Signification	Que faire
`401 Unauthorized`	Le jeton d'accès est manquant, expiré, mal formé, ou sa signature ne se valide pas.	Rafraîchissez en ré-échangeant vos identifiants API. Si l'échec persiste, votre intégration de délivrance de jeton est mal configurée.
`403 Forbidden`	Le jeton d'accès est valide, mais soit (a) vous n'avez pas la permission d'agir sur ce compte au nom de votre gestionnaire (la configuration de l'autorisation de compte à compte de votre plateforme est manquante ou n'a pas été synchronisée), soit (b) le `X-Platform-Parent-Account-Id` que vous avez envoyé ne correspond pas au parent réel du compte géré.	Vérifiez que l'`account_id` appartient à votre gestionnaire et que la valeur de l'en-tête est correcte. Si vous pensez que les deux sont corrects, déposez un ticket de support avec le `request_id` de l'enveloppe.
`422 Unprocessable`	Un en-tête requis est manquant lors d'une écriture. Le plus souvent `X-Platform-Parent-Account-Id`.	Ajoutez l'en-tête et réessayez avec la même clé d'idempotence.

Rotation du jeton d'accèsLien direct vers Rotation du jeton d'accès

Les jetons d'accès ont une durée de vie courte, environ 5 minutes. Votre client doit se rafraîchir à chaque requête, ou mettre en cache et se rafraîchir à l'expiration. Ne codez pas en dur les jetons d'accès, et n'intégrez jamais le client_secret à longue durée de vie dans le code côté client. Les jetons d'accès sont des JWTs, vous pouvez donc les décoder côté client pour inspecter la revendication exp lors du débogage des problèmes d'expiration ; rien d'autre dans le jeton d'accès ne fait partie du contrat partenaire.

Si un travail par lots de longue durée rencontre 401 en milieu de lot, ré-échangez vos identifiants API pour un nouveau jeton d'accès et réessayez. Avec Idempotency-Key, la réessai se réduit à une opération nulle pour toute écriture qui a déjà réussi dans la fenêtre de déduplication de 24 heures.

Rate limitsLien direct vers Rate limits

Vos identifiants API déterminent votre quota de requêtes par minute sur les points de terminaison à forte écriture. Chaque serveur de votre flotte utilisant le même client_id partage un seul seau. Voir Rate Limits pour les limites par point de terminaison et l'enveloppe 429.