Authentification

Cles API

AdaptlyPost utilise des cles API pour authentifier les requetes REST API. Vous pouvez generer et gerer vos cles API depuis votre tableau de bord sous Parametres > Jetons API.

Utiliser votre cle API

Incluez votre cle API dans l'en-tete Authorization de chaque requete :

Authorization: Bearer your_api_key_here

Exemple de requete

curl https://post.adaptlypost.com/post/api/v1/social-accounts \
  -H "Authorization: Bearer adaptly_8f3c1d9a7b2e4605c1a8d7f36b904e2d"

Rôles et permissions

Chaque membre d'un espace de travail a l'un de quatre rôles. Le rôle décide de ce que le membre peut faire dans le tableau de bord, et de ce que peut faire toute clé API, session MCP ou intégration agissant pour lui. La vérification s'exécute côté serveur à chaque requête, un client ne peut pas la contourner.

Permissions par rôle

Chaque page d'endpoint nomme la permission qu'il exige. Une clé détient exactement les permissions de son rôle, moins ce que son créateur ne peut plus faire. GET /api/v1/me renvoie la liste.

Les clés portent un rôle

Quand vous créez une clé, vous choisissez son rôle. La clé agit ensuite avec ce rôle dans l'espace de travail où elle a été créée, selon ces règles :

• Une clé ne peut jamais être créée avec un rôle supérieur à celui du membre qui la crée. Un Éditeur peut émettre des clés Éditeur, Contributeur ou Lecteur, pas de clés Administrateur.
• À chaque requête, les permissions effectives de la clé sont celles de son rôle, moins ce que son créateur ne peut plus faire. La vérification lit le rôle actuel du créateur, pas celui au moment de la création.
• Si le créateur est rétrogradé, toutes les clés qu'il a créées rétrécissent avec lui immédiatement. Une clé Éditeur créée par un membre devenu Contributeur ne peut plus que rédiger des brouillons.
• Si le créateur quitte l'espace de travail ou en est retiré, ses clés cessent de fonctionner et répondent 401 avec le code token_issuer_lost_access. Un administrateur de l'espace de travail en crée une de remplacement.
• Une session MCP ou une autorisation OAuth n'a pas de rôle propre : elle agit avec le rôle du membre connecté dans l'espace de travail où arrive l'appel. C'est son espace de travail par défaut, sauf si X-Workspace-Id en désigne un autre.

Choisir un espace de travail

Un membre peut faire partie de plusieurs espaces de travail, dans une ou plusieurs organisations. Une connexion OAuth, comme le connecteur Claude ou ChatGPT, peut agir dans chacun d'eux. Une clé API n'agit que dans l'espace de travail où elle a été créée. Envoyez l'en-tête facultatif X-Workspace-Id sur n'importe quelle requête pour choisir l'espace de travail. Sans lui, l'appel arrive dans l'espace de travail par défaut.

X-Workspace-Id: ag_02k7m

Cet endpoint liste les id d'espace de travail que vous pouvez envoyer, avec votre rôle et un objet can pour chacun : GET /api/v1/workspaces

Erreurs d'authentification

Une clé absente, invalide ou expirée répond 401. Une clé qui existe mais n'a pas le droit de faire ce que vous demandez répond 403. Chaque corps d'erreur porte un code lisible par machine pour qu'un client les distingue :

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

La clé est valide mais le membre qui l'a créée ne fait plus partie de l'espace de travail. La clé est morte pour de bon ; demandez-en une nouvelle à un administrateur de l'espace de travail.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "token_issuer_lost_access",
  "message": "This API key no longer works: the member who created it lost access to the workspace. Ask a workspace admin for a new key."
}

Une connexion OAuth, comme le connecteur Claude ou ChatGPT, a utilisé un e-mail sans compte AdaptlyPost. Déconnectez l'application et reconnectez-la avec l'e-mail que vous utilisez sur AdaptlyPost.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "oauth_account_not_found",
  "message": "You signed in as jane@example.com, which has no AdaptlyPost account. Disconnect this app and connect again with the email you use on AdaptlyPost."
}

Le rôle de la clé ne détient pas la permission qu'exige cette opération. Le corps nomme la permission manquante, le rôle avec lequel la clé agit, et quoi faire à la place. Pour une opération sur une publication, la permission requise dépend de la requête : publier maintenant exige posts.publish, un scheduledAt futur exige posts.schedule, et toucher à la publication d'un autre membre exige en plus posts.others.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "permission_denied",
  "requiredPermission": "posts.publish",
  "role": "contributor",
  "keyRole": "contributor",
  "issuerRole": "editor",
  "tokenType": "api_token",
  "message": "The Contributor role cannot publish posts. Send the post with saveAsDraft: true and ask a workspace member to publish it."
}

Le forfait de l'organisation n'est pas actif ou n'inclut pas l'accès à l'API. Chaque appel avec la clé ou la connexion OAuth reçoit cette réponse jusqu'au renouvellement ou à la mise à niveau du forfait. code distingue ce 403 des autres.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "subscription_required",
  "message": "This API key no longer works: your organization's plan does not include API access. Renew or upgrade the plan to use it again."
}

X-Workspace-Id désigne un espace de travail que l'appelant ne peut pas atteindre. Une clé API reçoit la même réponse pour tout espace de travail autre que le sien. Envoyez un id renvoyé par GET /api/v1/workspaces, ou omettez l'en-tête.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "ag_03p4r",
  "message": "You have no access to workspace ag_03p4r. Call GET /workspaces to list the workspaces you can use, and send one of those ids in the X-Workspace-Id header."
}

Pour les équipes réglementées

Un siège Contributeur et une clé Contributeur sont appliqués côté serveur, pas dans l'interface. Chaque requête, qu'elle vienne du tableau de bord, de l'API REST, du serveur MCP ou d'une intégration comme Zapier ou n8n, passe par la même vérification de permissions dans le service de publication avant toute écriture : la vérification lit le rôle de l'appelant dans l'espace de travail à cet instant, déduit la permission requise des faits de la requête (brouillon, planifiée ou publier maintenant ; publication personnelle ou d'un collègue) et refuse avec un 403 si elle manque. Une clé est créée sous un rôle, jamais au-dessus de celui du membre qui la crée, et ses permissions sont recalculées à chaque appel comme l'intersection du rôle de la clé et du rôle actuel de son créateur : rétrograder le créateur réduit la clé immédiatement, le retirer la tue. Un auditeur peut s'appuyer sur trois éléments : GET /api/v1/me, qui renvoie le rôle et la liste exacte des permissions d'une clé à cet instant ; le corps du 403, qui nomme la permission manquante, le rôle qui ne l'avait pas et le type de jeton qui a essayé ; et le journal d'audit des publications, où chaque tentative de création, planification, publication, nouvel essai ou suppression est enregistrée avec son auteur, la clé utilisée, le rôle, le statut de départ et d'arrivée, et si elle a été acceptée ou refusée. Le journal est écrit par le service de publication ; il n'est pas encore consultable depuis le tableau de bord ni depuis l'API.