Scope

Ogni operazione richiede esattamente uno scope, denominato <resource>.<action>, per esempio:

shifts.read        locations.write        timesheets.read

• GET richiede .read.

• POST, PATCH, DELETE richiedono .write.

• La scrittura implica la lettura — shifts.write soddisfa anche shifts.read, quindi non serve mai richiedere entrambi.

Ogni operazione nella Referenza API dichiara lo scope esatto che richiede, direttamente sull’operazione. Quel requisito deriva dallo stesso valore che legge il controllo dei permessi sul server, quindi ciò che è documentato e ciò che è applicato non possono divergere.

Chiedere quelli giusti

Gli scope vengono concessi per singolo client di integrazione al momento della registrazione, quindi chiedi ciò che l’integrazione fa realmente e nulla di più. Un export dei salari che legge le ore ottiene timesheets.read e nient’altro.

Un errore di battitura viene individuato alla registrazione, non in esecuzione: shift.read viene rifiutato con un suggerimento, invece di registrare un client che fallisce a ogni chiamata.

Per aggiungere uno scope in seguito, scrivi all’assistenza — non servono nuove credenziali.

Quando manca uno scope

Una chiamata con un token valido ma senza l’autorizzazione richiesta è:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "…",
    "details": []
  }
}

con stato 403. È distinto da un 401 (è il token stesso a non essere valido — vedi Autenticazione) e da un 404, che è anche ciò che ottieni per un record al di fuori della tua azienda, così l’esistenza non traspare mai.