Autenticazione

Personal access token

La via più rapida per iniziare. Un token personale è legato al tuo account e non può mai vedere i dati di nessun altro: perfetto per dashboard, script, fogli di calcolo e progetti personali.

Crea un token

I token personali si gestiscono dal tuo account, quindi questi tre endpoint usano la tua normale sessione Gravl (la stessa autenticazione dell'app mobile), non il token stesso.

Creazione

POST https://api.gravl.ai/api/user/personal-tokens
Authorization: Bearer <your Gravl session token>
Content-Type: application/json

{
  "name": "My stats dashboard",
  "scopes": ["workouts:read", "stats:read"],
  "expiresInDays": 365
}

{
  "token": "gat_k3rB…",          // ← shown exactly once, store it now
  "clientId": "gci_9fJq…",
  "name": "My stats dashboard",
  "scopes": "workouts:read stats:read",
  "expiresAt": "2027-07-14T09:30:00Z"
}

Campo	Tipo	Note
`name`	string	Obbligatorio. Cosa stai costruendo: viene mostrato quando elenchi i tuoi token. Max 120 caratteri.
`scopes`	string[]	Facoltativo. Il default sono tutti gli scope (sono i tuoi dati). Vedi scope.
`expiresInDays`	number	Facoltativo. Da 1 a 365; il default è 365.

Il valore di token viene restituito una sola volta e salvato solo come hash. Se lo perdi, revoca e ricrea: non c'è modo di rileggerlo.

Usalo

Invia il token come bearer token verso qualsiasi endpoint /api/v1 per cui ha gli scope:

curl "https://api.gravl.ai/api/v1/stats" \
  -H "Authorization: Bearer gat_k3rB…"

{
  "streak": { "current": 6, "longest": 14, "workoutsThisWeek": 3 },
  "totalXp": 12480,
  "trophyCount": 22
}

Elenca e revoca

Metodo	Percorso	Descrizione
GET	`/api/user/personal-tokens`	I tuoi token attivi: nome, clientId, scope, data di creazione, ultimo utilizzo, scadenza. Mai il valore del token.
DELETE	`/api/user/personal-tokens/{clientId}`	Revoca il token immediatamente. Le richieste in corso che lo usano iniziano subito a fallire con 401.

Limiti

Limite	Valore
Token attivi per account	10
Durata massima	365 giorni
Rate limit	100 richieste / 15 minuti (per token per utente)

Ti servono automazioni più longeve, accesso app-to-app o limiti più alti? È a questo che servono le app OAuth.