Autenticazione

Ogni chiamata porta un token Bearer nell'header Authorization. Sofia rilegge i diritti collegati a ogni chiamata: una persona rimossa da un Workspace, o un'autorizzazione revocata, ferma il token alla richiesta successiva.

Chiavi personali

Crea una chiave in Impostazioni › API › Accesso personale. Agisce per te su tutti i tuoi Workspace: l'attività che indichi stabilisce il Workspace, e il tuo ruolo lì decide cosa può fare la chiave.

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

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:

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:

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

• 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.

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.

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)

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

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