Authentification

Tokens d’accès personnels

Le chemin le plus rapide. Un token personnel est lié à ton propre compte et ne peut jamais voir les données de quelqu’un d’autre : parfait pour les dashboards, les scripts, les tableurs et les side projects.

Créer un token

Les tokens personnels se gèrent depuis ton propre compte : ces trois endpoints utilisent donc ta session Gravl normale (la même authentification que l’app mobile), pas le token lui-même.

Créer

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

Champ	Type	Notes
`name`	string	Requis. Ce que tu construis : affiché quand tu listes tes tokens. 120 caractères max.
`scopes`	string[]	Optionnel. Par défaut, tous les scopes (ce sont tes propres données). Voir scopes.
`expiresInDays`	number	Optionnel. 1 à 365 ; 365 par défaut.

La valeur token n’est renvoyée qu’une seule fois et stockée uniquement sous forme de hash. Si tu la perds, tu révoques et tu recrées : il n’existe aucun moyen de la relire.

L’utiliser

Envoie le token comme bearer token sur n’importe quel endpoint /api/v1 couvert par ses scopes :

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

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

Lister et révoquer

Méthode	Chemin	Description
GET	`/api/user/personal-tokens`	Tes tokens actifs : nom, clientId, scopes, création, dernière utilisation, expiration. Jamais la valeur du token.
DELETE	`/api/user/personal-tokens/{clientId}`	Révoque le token immédiatement. Les requêtes en cours avec ce token se mettent aussitôt à échouer en 401.

Limites

Limite	Valeur
Tokens actifs par compte	10
Durée de vie maximale	365 jours
Rate limit	100 requêtes / 15 minutes (par token et par utilisateur)

Besoin d’automatisations plus durables, d’un accès app à app ou de limites plus élevées ? C’est exactement le rôle des apps OAuth.