Autenticazione

L’API usa OAuth2 client_credentials — il grant da macchina a macchina. Non c’è utente, né reindirizzamento del browser, né schermata di consenso.

Sono coinvolti due host e il tuo client dialoga con entrambi:

Ruolo	Host	Scopo
Provider di identità	https://auth.shiftavo.com	emette i token
Shard	dal claim api_base del tuo token	serve i dati

Presentare le tue credenziali

Sono accettati entrambi i metodi standard di autenticazione del client OAuth2 (RFC 6749 §2.3.1). Usa quello che la tua libreria HTTP o OAuth rende più semplice: qui sono equivalenti.

client_secret_post — credenziali nel corpo del formulario:

POST /identity/o/api/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=cust-acme-integration
client_secret=<secret>
scope=shifts.read

client_secret_basic — credenziali in un header HTTP Basic, nel corpo solo client_id:

POST /identity/o/api/token HTTP/1.1
Authorization: Basic base64("cust-acme-integration:<secret>")
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=cust-acme-integration
scope=shifts.read

client_secret_basic è il valore predefinito della specifica ed è quello che emette la maggior parte delle librerie OAuth già pronte; client_secret_post è più semplice da costruire a mano, senza il passaggio base64.

Scadenza e rinnovo

I token durano per impostazione predefinita 1800 secondi. Il grant client_credentials non ha refresh token — per scelta progettuale (RFC 6749 §4.4.3), e non ti costa nulla: il tuo client possiede già client_id e client_secret, quindi «rinnovare» significa semplicemente chiedere un nuovo token con la stessa chiamata. Un refresh token sarebbe solo un altro segreto da conservare.

Due regole rendono robusto un client:

• Memorizza in cache il token e riutilizzalo fino a poco prima di expires_in. Rinnovarlo ~30 secondi in anticipo evita le corse critiche al limite della scadenza.

• In caso di 401 dall’API dei dati — un token può essere invalidato in anticipo, per esempio da una rigenerazione delle chiavi — elimina il token in cache, richiedine uno nuovo e ripeti la richiesta una volta.

Routing: il claim api_base

Il token è un JWT. Oltre ai campi OAuth standard contiene:

Claim	Esempio	Significato
api_base	https://app.shiftavo.com	URL di base dell’host da chiamare
aud	["https://app.shiftavo.com/api"]	API dello shard di destinazione
tenant_id	0194d1c0-…	L’azienda a cui sei vincolato
tenant_name	Acme	Nome visualizzato
tenant_status	active	Alle aziende non attive il token viene rifiutato

Leggi api_base e chiama quell’host. Mantieni un fallback configurato per il caso in cui il claim sia assente, ma dai la preferenza al claim: è ciò che ci permette di aggiungere o spostare uno shard senza alcuna modifica da parte tua.

aud e il vincolo con l’azienda vengono impostati lato server in base al tenant a cui appartengono le tue credenziali. Non sono richiedibili: un client non può fisicamente puntare a un’altra azienda o a un altro shard.

Cosa non è un token macchina

I token macchina non hanno sub né claim di utente o di appartenenza. Ogni chiamata agisce come l’integrazione stessa, limitata dai suoi scope. Due conseguenze:

• L’API non può dedurre chi è responsabile di una scrittura, quindi alcune scritture ti obbligano a indicare esplicitamente una persona — vedi Indicare la persona dietro una scrittura.

• Un token utente di prima parte (dall’app web o mobile) viene rifiutato su questa superficie. È riservato alle macchine.

Errori in questa fase

Sintomo	Causa
401 dall’endpoint del token	client_id / client_secret errati, oppure l’azienda è sospesa
400 invalid_scope all’endpoint del token	hai richiesto uno scope che non è stato concesso al tuo client
401 dall’API dei dati	token scaduto, non valido o invalidato in anticipo — rinnovalo e riprova una volta
403 insufficient_scope dall’API dei dati	token valido, autorizzazione mancante — vedi Scope