OAuth2

Authentification OAuth2

Connectez votre app à d’autres comptes Sofia : enregistrez un client, suivez le flux authorization code avec PKCE, renouvelez les jetons et demandez les scopes.

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 :

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

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 :

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

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.

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

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.

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

Permissions (scopes)

Scope	Autorise
`establishments:read`	Lister les établissements
`accounts:read`, `accounts:write`	Lire les réseaux connectés ; créer des liens de connexion
`media:read`, `media:write`	Lire la médiathèque ; téléverser et importer des médias
`posts:read`, `posts:write`	Lister et suivre les publications ; les publier, les modifier et les supprimer
`insights:read`	Lire les statistiques
`webhooks:read`, `webhooks:write`	Lister les webhooks ; les enregistrer, les tester et les supprimer
`offline_access`	OAuth uniquement : recevoir un refresh token

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 :

text

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