Autenticação

Tokens de acesso pessoais

A forma mais rápida de entrar. Um token pessoal está associado à sua própria conta e nunca pode ver os dados de outra pessoa: perfeito para dashboards, scripts, folhas de cálculo e projetos pessoais.

Criar um token

Os tokens pessoais são geridos a partir da sua própria conta, por isso estes três endpoints usam a sua sessão normal do Gravl (a mesma autenticação que a app móvel usa), não o próprio token.

Criar

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	Notas
`name`	string	Obrigatório. O que está a construir; aparece quando lista os seus tokens. Máximo 120 caracteres.
`scopes`	string[]	Opcional. Por omissão são todos os scopes (os dados são seus). Ver scopes.
`expiresInDays`	number	Opcional. 1–365; por omissão 365.

O valor de token é devolvido uma única vez e guardado apenas como hash. Se o perder, revoga e cria outro; não há forma de o voltar a ler.

Usar o token

Envie o token como bearer token para qualquer endpoint /api/v1 para o qual tenha 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
}

Listar e revogar

Método	Caminho	Descrição
GET	`/api/user/personal-tokens`	Os seus tokens ativos: nome, clientId, scopes, criação, última utilização, expiração. Nunca o valor do token.
DELETE	`/api/user/personal-tokens/{clientId}`	Revoga o token imediatamente. Os pedidos em curso com ele passam logo a falhar com 401.

Limites

Limite	Valor
Tokens ativos por conta	10
Duração máxima	365 dias
Limite de pedidos	100 pedidos / 15 minutos (por token e por utilizador)

Precisa de automação mais duradoura, acesso app-a-app ou limites mais altos? É para isso que servem as apps OAuth.