OAuth2

Autenticazione OAuth2

Lascia che altri account Sofia colleghino la tua app: registra un client, esegui il flusso authorization code con PKCE, rinnova i token e chiedi gli scope.

OAuth: authorization code con PKCE

Registra un client in Impostazioni › API › Client applicativi: nome, logo, informativa sulla privacy, i permessi che può richiedere e i suoi URL di reindirizzamento https. Un client confidenziale ha un secret; un client pubblico (app mobile, estensione del browser) non ne ha e si affida solo a PKCE.

Manda la persona all'endpoint di autorizzazione con una challenge PKCE (S256 è obbligatorio) e uno state che conservi nella sua sessione:

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 persona accede a Sofia, vede il tuo nome, il tuo logo e i tuoi permessi, sceglie un Workspace e accetta. Sofia la rimanda quindi al tuo URL di reindirizzamento con un code, il tuo state e l'emittente iss. Verifica entrambi, poi scambia il 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_…"
}

Il code è valido 5 minuti, una sola volta. Se riutilizzato, viene rifiutato e i token che ha dato smettono di funzionare.
L'access token dura un'ora e agisce solo sul Workspace scelto dalla persona.
Un refresh_token viene restituito solo se hai chiesto offline_access. È monouso: conserva ogni volta il nuovo. Riutilizzare un refresh token già usato revoca l'intera autorizzazione.

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 confidenziale può anche agire su un Workspace di proprietà del suo titolare, senza una persona nel mezzo. Quando il client possiede più Workspace, indicane uno con 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

Permessi (scope)

Scope	Consente
`establishments:read`	Elencare le attività
`accounts:read`, `accounts:write`	Leggere le reti collegate; creare link di collegamento
`media:read`, `media:write`	Leggere la mediateca; caricare e importare media
`posts:read`, `posts:write`	Elencare e seguire le pubblicazioni; pubblicarle, modificarle ed eliminarle
`insights:read`	Leggere le statistiche
`webhooks:read`, `webhooks:write`	Elencare i webhook; registrarli, testarli ed eliminarli
`offline_access`	Solo OAuth: ricevere un refresh token

Una chiamata senza lo scope necessario risponde 403 insufficient_scope. I metadati del server (RFC 8414) elencano ogni endpoint e ogni scope:

text

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