Authentifizierung

API-Schlüssel

AdaptlyPost verwendet API-Schlüssel zur Authentifizierung von REST API-Anfragen. Sie können API-Schlüssel in Ihrem Dashboard unter Einstellungen > API-Tokens erstellen und verwalten.

Verwendung Ihres API-Schlüssels

Fügen Sie Ihren API-Schlüssel im Authorization-Header jeder Anfrage ein:

Authorization: Bearer your_api_key_here

Beispielanfrage

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

Rollen und Berechtigungen

Jedes Mitglied eines Workspace hat eine von vier Rollen. Die Rolle entscheidet, was das Mitglied im Dashboard tun darf und was jeder API-Schlüssel, jede MCP-Sitzung und jede Integration darf, die in seinem Namen handelt. Die Prüfung läuft bei jeder Anfrage auf dem Server, ein Client kann sie nicht umgehen.

Berechtigungen nach Rolle

Jede Endpunktseite nennt die benötigte Berechtigung. Ein Schlüssel hält genau die Berechtigungen seiner Rolle, abzüglich allem, was sein Ersteller nicht mehr darf. GET /api/v1/me gibt die Liste zurück.

Schlüssel tragen eine Rolle

Beim Erstellen eines Schlüssels wählen Sie seine Rolle. Der Schlüssel handelt dann mit dieser Rolle in dem Workspace, in dem er erstellt wurde, nach diesen Regeln:

• Ein Schlüssel kann nie mit einer Rolle über der des erstellenden Mitglieds erstellt werden. Ein Redakteur kann Redakteur-, Mitwirkenden- oder Betrachter-Schlüssel erstellen, keine Admin-Schlüssel.
• Bei jeder Anfrage sind die wirksamen Berechtigungen des Schlüssels die seiner Rolle, abzüglich allem, was sein Ersteller nicht mehr darf. Die Prüfung liest die aktuelle Rolle des Erstellers, nicht die Rolle zum Zeitpunkt der Erstellung.
• Wird der Ersteller herabgestuft, schrumpfen alle von ihm erstellten Schlüssel sofort mit. Ein Redakteur-Schlüssel eines Mitglieds, das jetzt Mitwirkender ist, kann nur noch Entwürfe anlegen.
• Verlässt der Ersteller den Workspace oder wird entfernt, funktionieren seine Schlüssel nicht mehr und antworten mit 401 und code token_issuer_lost_access. Ein Workspace-Admin erstellt einen Ersatz.
• Eine MCP-Sitzung oder ein OAuth-Grant hat keine eigene Rolle: Sie handelt mit der Rolle des angemeldeten Mitglieds in dem Workspace, in dem der Aufruf landet. Das ist dessen Standard-Workspace, sofern X-Workspace-Id keinen anderen nennt.

Workspace wählen

Ein Mitglied kann zu mehreren Workspaces gehören, in einer oder mehreren Organisationen. Eine OAuth-Verbindung, etwa der Claude- oder ChatGPT-Connector, kann in jedem davon handeln. Ein API-Schlüssel handelt nur in dem Workspace, in dem er erstellt wurde. Senden Sie bei einer beliebigen Anfrage den optionalen Header X-Workspace-Id, um den Workspace zu wählen. Ohne ihn landet der Aufruf im Standard-Workspace.

X-Workspace-Id: ag_02k7m

Dieser Endpunkt listet die Workspace-IDs auf, die Sie senden können, jeweils mit Ihrer Rolle und einem can-Objekt: GET /api/v1/workspaces

Authentifizierungsfehler

Ein fehlender, ungültiger oder abgelaufener Schlüssel antwortet mit 401. Ein Schlüssel, der existiert, aber das Angefragte nicht darf, antwortet mit 403. Jeder Fehler-Body enthält einen maschinenlesbaren code, damit ein Client die Fälle unterscheiden kann:

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

Der Schlüssel ist gültig, aber das Mitglied, das ihn erstellt hat, gehört nicht mehr zum Workspace. Der Schlüssel ist endgültig tot; bitten Sie einen Workspace-Admin um einen neuen.

{
  "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."
}

Eine OAuth-Anmeldung, etwa über den Claude- oder ChatGPT-Connector, hat eine E-Mail-Adresse ohne AdaptlyPost-Konto verwendet. Trennen Sie die App und verbinden Sie sie erneut mit der E-Mail-Adresse, die Sie bei AdaptlyPost nutzen.

{
  "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."
}

Die Rolle des Schlüssels hält die für diesen Vorgang nötige Berechtigung nicht. Der Body nennt die fehlende Berechtigung, die Rolle, als die der Schlüssel handelt, und was stattdessen zu tun ist. Bei Beitragsvorgängen hängt die nötige Berechtigung von der Anfrage ab: Sofort veröffentlichen braucht posts.publish, ein zukünftiges scheduledAt braucht posts.schedule, und der Beitrag eines anderen Mitglieds braucht zusätzlich 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."
}

Der Plan der Organisation ist nicht aktiv oder enthält keinen API-Zugang. Jeder Aufruf mit dem Schlüssel oder der OAuth-Anmeldung erhält diese Antwort, bis der Plan verlängert oder hochgestuft wird. code unterscheidet diesen 403 von den anderen.

{
  "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 nennt einen Workspace, den der Aufrufer nicht erreicht. Ein API-Schlüssel erhält dieselbe Antwort für jeden Workspace außer seinem eigenen. Senden Sie eine id aus GET /api/v1/workspaces oder lassen Sie den Header weg.

{
  "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."
}

Für regulierte Teams

Ein Mitwirkenden-Sitz und ein Mitwirkenden-Schlüssel werden auf dem Server durchgesetzt, nicht in der Oberfläche. Jede Anfrage, ob aus dem Dashboard, der REST API, dem MCP-Server oder einer Integration wie Zapier oder n8n, durchläuft dieselbe Berechtigungsprüfung im Post-Dienst, bevor etwas geschrieben wird: Die Prüfung liest die Rolle des Aufrufers im Workspace zu diesem Zeitpunkt, leitet aus den Fakten der Anfrage die benötigte Berechtigung ab (Entwurf, geplant oder sofort veröffentlichen; eigener Beitrag oder der eines Teammitglieds) und lehnt mit 403 ab, wenn sie fehlt. Ein Schlüssel wird unter einer Rolle erstellt, nie über der des erstellenden Mitglieds, und seine Berechtigungen werden bei jedem Aufruf als Schnittmenge aus der Rolle des Schlüssels und der aktuellen Rolle des Erstellers neu berechnet. Wird der Ersteller herabgestuft, schrumpft der Schlüssel sofort mit; wird er entfernt, stirbt der Schlüssel. Ein Prüfer kann auf drei Dinge verweisen: GET /api/v1/me, das die Rolle und die genaue Berechtigungsliste eines Schlüssels zum jetzigen Zeitpunkt zurückgibt; den 403-Body, der die fehlende Berechtigung, die Rolle, der sie fehlte, und die Art des Tokens nennt; und das Beitrags-Audit-Protokoll, in dem jeder Versuch zu erstellen, zu planen, zu veröffentlichen, zu wiederholen oder zu löschen festgehalten wird, mit Angabe, wer es getan hat, über welchen Schlüssel, unter welcher Rolle, von welchem Status zu welchem, und ob er erlaubt oder abgelehnt wurde. Das Protokoll schreibt der Post-Dienst; im Dashboard und über die API ist es noch nicht abrufbar.