Authentification

Chaque appel porte un jeton Bearer dans l’en-tête Authorization. Sofia relit les droits qui s’y rattachent à chaque appel : une personne retirée d’un Workspace, ou une autorisation révoquée, arrête le jeton dès la requête suivante.

Clés personnelles

Créez une clé dans Réglages › API › Accès personnel. Elle agit pour vous sur tous vos Workspaces : l’établissement que vous nommez détermine le Workspace, et votre rôle dans celui-ci décide de ce que la clé peut faire.

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

OAuth : code d’autorisation avec PKCE

Enregistrez un client dans Réglages › API › Clients d’application : son nom, son logo, sa politique de confidentialité, les permissions qu’il peut demander et ses URL de redirection https. Un client confidentiel possède un secret ; un client public (app mobile, extension de navigateur) n’en a pas et s’appuie uniquement sur PKCE.

Envoyez la personne vers l’endpoint d’autorisation avec un challenge PKCE (S256 est obligatoire) et un state que vous conservez dans sa session :

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();

La personne se connecte à Sofia, voit votre nom, votre logo et vos permissions, choisit un Workspace et accepte. Sofia la renvoie alors vers votre URL de redirection avec un code, votre state et l’émetteur iss. Vérifiez les deux, puis échangez le code :

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_…"
}

• Le code est valable 5 minutes, une seule fois. Rejoué, il est refusé et les jetons qu’il a donnés cessent de fonctionner.
• Le jeton d’accès dure une heure et n’agit que sur le Workspace choisi par la personne.
• Un refresh_token n’est renvoyé que si vous avez demandé offline_access. Il est à usage unique : conservez le nouveau à chaque fois. Rejouer un refresh token déjà utilisé révoque toute l’autorisation.

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

Un client confidentiel peut aussi agir sur un Workspace que son propriétaire possède, sans personne dans la boucle. Quand le client détient plusieurs Workspaces, nommez-en un avec workspace_id.

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

Permissions (scopes)

Un appel sans le scope requis répond 403 insufficient_scope. Les métadonnées du serveur (RFC 8414) listent chaque endpoint et chaque scope :

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