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

Am einfachsten geht es über das Dashboard: Öffne app.gravl.ai/settings/developer und erstelle den Token dort — benenne ihn, wähle Scopes und Ablaufdatum und kopiere den Wert, sobald er angezeigt wird. Die Endpoints unten machen dasselbe programmatisch.

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.