Authentifizierung

Persönliche Access Tokens

Der schnellste Weg rein. Ein persönliches Token ist an deinen eigenen Account gebunden und kann niemals die Daten anderer sehen; perfekt für Dashboards, Skripte, Spreadsheets und Side Projects.

Token erstellen

Persönliche Tokens verwaltest du in deinem eigenen Account. Diese drei Endpoints nutzen deshalb deine normale Gravl-Session (dieselbe Authentifizierung wie die mobile App), nicht das Token selbst.

Erstellen

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

Feld	Typ	Hinweise
`name`	string	Erforderlich. Was du baust; wird angezeigt, wenn du deine Tokens auflistest. Max. 120 Zeichen.
`scopes`	string[]	Optional. Standard sind alle Scopes (es sind deine eigenen Daten). Siehe Scopes.
`expiresInDays`	number	Optional. 1–365; Standard ist 365.

Der token-Wert wird genau einmal zurückgegeben und nur als Hash gespeichert. Verlierst du ihn, bleibt nur Widerrufen und neu Erstellen; es gibt keinen Weg, ihn erneut auszulesen.

Token verwenden

Sende das Token als Bearer Token an jeden /api/v1-Endpoint, für den es Scopes hat:

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

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

Auflisten und widerrufen

Methode	Pfad	Beschreibung
GET	`/api/user/personal-tokens`	Deine aktiven Tokens: Name, clientId, Scopes, Erstellung, letzte Nutzung, Ablauf. Niemals der Token-Wert selbst.
DELETE	`/api/user/personal-tokens/{clientId}`	Widerruft das Token sofort. Laufende Requests damit schlagen ab diesem Moment mit 401 fehl.

Limits

Limit	Wert
Aktive Tokens pro Account	10
Maximale Lebensdauer	365 Tage
Rate Limit	100 Requests / 15 Minuten (pro Token pro Nutzer)

Du brauchst langlebigere Automatisierung, App-zu-App-Zugriff oder höhere Limits? Genau dafür gibt es OAuth-Apps.