OAuth2

OAuth2-Authentifizierung

Andere Sofia-Konten mit deiner App verbinden: Client registrieren, Authorization-Code-Flow mit PKCE ausführen, Tokens erneuern, Scopes anfordern.

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:

javascript

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:

bash

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

json

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

bash

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.

bash

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)

Scope	Erlaubt
`establishments:read`	Betriebe auflisten
`accounts:read`, `accounts:write`	Verbundene Netzwerke lesen; Verbindungslinks erstellen
`media:read`, `media:write`	Die Mediathek lesen; Medien hochladen und importieren
`posts:read`, `posts:write`	Beiträge auflisten und verfolgen; veröffentlichen, bearbeiten und löschen
`insights:read`	Statistiken lesen
`webhooks:read`, `webhooks:write`	Webhooks auflisten; registrieren, testen und löschen
`offline_access`	Nur OAuth: ein Refresh-Token erhalten

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

text

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