Authentifizierung

Jeder Aufruf trägt ein Bearer-Token im Header Authorization. Sofia liest die dahinterliegenden Rechte bei jedem Aufruf neu: Wird eine Person aus einem Workspace entfernt oder eine Autorisierung widerrufen, stoppt das Token bei der nächsten Anfrage.

Persönliche Schlüssel

Erstellen Sie einen Schlüssel unter Einstellungen › API › Persönlicher Zugriff. Er handelt für Sie in allen Ihren Workspaces: Der Betrieb, den Sie angeben, legt den Workspace fest, und Ihre Rolle dort bestimmt, was der Schlüssel darf.

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_pk_live_…"

OAuth: Authorization Code mit PKCE

Registrieren Sie einen Client unter Einstellungen › API › App-Clients: Name, Logo, Datenschutzerklärung, die Berechtigungen, die er anfordern darf, und seine https-Redirect-URLs. Ein vertraulicher Client hat ein Secret; ein öffentlicher Client (Mobile-App, Browser-Erweiterung) hat keines und stützt sich allein auf PKCE.

Leiten Sie die Person mit einer PKCE-Challenge (S256 ist Pflicht) und einem state, den Sie in ihrer Sitzung aufbewahren, zum Authorization-Endpoint:

import { createHash, randomBytes } from 'node:crypto';

const verifier = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const state = randomBytes(16).toString('base64url');

const url = new URL('https://api.sofia-post.com/api/v1/oauth/authorize');
url.search = new URLSearchParams({
  response_type: 'code',
  client_id: process.env.SOFIA_CLIENT_ID,
  redirect_uri: 'https://app.example.com/oauth/callback',
  scope: 'establishments:read posts:read posts:write offline_access',
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256',
}).toString();

Die Person meldet sich bei Sofia an, sieht Ihren Namen, Ihr Logo und Ihre Berechtigungen, wählt einen Workspace und stimmt zu. Sofia leitet sie dann mit einem code, Ihrem state und dem Aussteller iss zu Ihrer Redirect-URL zurück. Prüfen Sie beides, dann tauschen Sie den Code ein:

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d code_verifier=$VERIFIER

{
  "access_token": "sofia_live_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "establishments:read posts:read posts:write offline_access",
  "refresh_token": "sofia_live_rt_…"
}

• Der Code ist 5 Minuten gültig, einmalig. Wird er erneut verwendet, wird er abgelehnt und die damit ausgestellten Tokens funktionieren nicht mehr.
• Das Access-Token gilt eine Stunde und handelt nur im Workspace, den die Person gewählt hat.
• Ein refresh_token wird nur zurückgegeben, wenn Sie offline_access angefordert haben. Es ist einmalig verwendbar: Behalten Sie jedes Mal das neue. Wird ein bereits benutztes Refresh-Token erneut verwendet, wird die gesamte Autorisierung widerrufen.

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

OAuth: Client Credentials

Ein vertraulicher Client kann auch ohne beteiligte Person in einem Workspace handeln, den sein Inhaber besitzt. Hält der Client mehrere Workspaces, geben Sie einen mit workspace_id an.

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d workspace_id=$WORKSPACE_ID

Berechtigungen (Scopes)

Ein Aufruf ohne den nötigen Scope antwortet mit 403 insufficient_scope. Die Server-Metadaten (RFC 8414) listen jeden Endpoint und jeden Scope auf:

https://api.sofia-post.com/.well-known/oauth-authorization-server/api/v1/oauth