Authentication

Personal access tokens

The fastest way in. A personal token is bound to your own account and can never see anyone else’s data — perfect for dashboards, scripts, spreadsheets and side projects.

Create a token

Personal tokens are managed from your own account, so these three endpoints use your normal Gravl session (the same authentication the mobile app uses) — not the token itself.

Create

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

Field	Type	Notes
`name`	string	Required. What you’re building — shown when you list your tokens. Max 120 chars.
`scopes`	string[]	Optional. Defaults to all scopes (it’s your own data). See scopes.
`expiresInDays`	number	Optional. 1–365; defaults to 365.

The token value is returned once and stored only as a hash. Lose it and you revoke + recreate — there is no way to read it back.

Use it

Send the token as a bearer token against any /api/v1 endpoint it has scopes for:

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

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

List and revoke

Method	Path	Description
GET	`/api/user/personal-tokens`	Your active tokens — name, clientId, scopes, created, last used, expiry. Never the token value.
DELETE	`/api/user/personal-tokens/{clientId}`	Revokes the token immediately. In-flight requests with it start failing with 401 right away.

Limits

Limit	Value
Active tokens per account	10
Maximum lifetime	365 days
Rate limit	100 requests / 15 minutes (per token per user)

Need longer-lived automation, app-to-app access, or higher limits? That’s what OAuth apps are for.