Apps OAuth

1. Registe a sua app

O registo é feito por si. Inicie sessão com a sua conta Gravl em app.gravl.ai/settings/developer e abra a secção Apps OAuth, ao lado dos seus tokens de acesso pessoais.

Aí indica:

• O nome da sua app e uma breve descrição do que faz; o nome não pode conter “Gravl”
• Um logótipo opcional: um PNG, JPEG ou WebP quadrado (SVG não é aceite), com pelo menos 128×128 px e no máximo 1 MB. Aparece no ecrã de consentimento ao lado do nome da sua app
• A página inicial da sua app: uma URL https
• Até 5 redirect URIs: URLs https absolutas (http://localhost permitido para desenvolvimento)
• Os scopes de que a sua app precisa. Peça o mínimo; os utilizadores veem exatamente o que pedir
• O tipo de cliente: confidencial para apps do lado do servidor que conseguem guardar um client_secret, ou público para apps de browser e nativas, que não recebem secret e têm de usar PKCE

Recebe de imediato um client_id (gci_…). Os clientes confidenciais recebem também um client_secret (gcs_…, mostrado uma única vez; guarde-o como uma password). Pode renovar o secret mais tarde na mesma página. Cada conta pode ter até 5 apps OAuth.

Modo de desenvolvimento e revisão

Uma app nova começa em modo de desenvolvimento. Funciona de imediato, mas só a sua própria conta Gravl a pode autorizar: os outros utilizadores veem um aviso no ecrã de consentimento e não conseguem ligar-se. Use este modo para construir e testar todo o fluxo.

• Quando a app estiver pronta, clique em Enviar para revisão. Verificamos o nome, a descrição, o logótipo, a página inicial, as redirect URIs e os scopes, e enviamos-lhe a decisão por email
• Depois da aprovação, qualquer utilizador do Gravl pode ligar a sua app
• Se a rejeitarmos, o email e a página de definições mostram o motivo; edite a app e submeta-a novamente
• As apps aprovadas não podem ser editadas na página de definições, incluindo o logótipo

Para alterar uma app aprovada, ou para qualquer dúvida sobre o registo ou a revisão, escreva para developers@gravl.ai.

2. Envie o utilizador para o ecrã de consentimento

https://api.gravl.ai/oauth/authorize
  ?client_id=gci_…
  &redirect_uri=https://yourapp.example/callback   // must be registered exactly
  &scope=workouts:read stats:read                  // omit for all allowed scopes
  &state=<random value you verify on return>
  &code_challenge=<S256(code_verifier)>
  &code_challenge_method=S256

O utilizador inicia sessão com a sua conta Gravl, vê o nome da sua app e os scopes pedidos em linguagem simples e aprova. O browser regressa à sua redirect_uri com ?code=gac_…&state=… (ou error=access_denied se cancelar).

• Os códigos têm o prefixo gac_, são válidos por 10 minutos, de utilização única e ficam vinculados à sua app e à redirect_uri para a qual foram emitidos
• O PKCE (S256) é obrigatório para clientes públicos (apps de browser ou nativas, que não têm client_secret) e fortemente recomendado para todos
• Verifique sempre que state corresponde ao que enviou; é a sua proteção CSRF

Os clientes públicos omitem o client_secret no endpoint de token; o PKCE é a sua autenticação de cliente. Escolhe o tipo de cliente quando cria a app.

3. Troque o código

curl -X POST https://api.gravl.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=gac_… \
  -d client_id=gci_… \
  -d client_secret=gcs_… \
  -d code_verifier=<your PKCE verifier> \
  -d redirect_uri=https://yourapp.example/callback

{
  "access_token": "gat_…",
  "token_type": "Bearer",
  "expires_in": 21600,
  "refresh_token": "grt_…",
  "scope": "workouts:read stats:read"
}

4. Renovar

curl -X POST https://api.gravl.ai/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=grt_… \
  -d client_id=gci_… \
  -d client_secret=gcs_…

A resposta tem a mesma forma da troca de código. O refresh token apresentado é revogado na mesma transação, por isso persista sempre o novo refresh_token antes de descartar o antigo. Reutilizar um refresh token já usado devolve invalid_grant.

5. Revogar

curl -X POST https://api.gravl.ai/oauth/revoke \
  -d token=grt_… \
  -d client_id=gci_… \
  -d client_secret=gcs_…

• Revogar um access token elimina apenas esse token
• Revogar um refresh token revoga o grant inteiro: todos os tokens em circulação para esse par utilizador + app
• Conforme a RFC 7009, o endpoint devolve 200 mesmo para tokens desconhecidos; só credenciais de cliente inválidas produzem erro
• Os utilizadores também podem revogar o acesso da sua app a partir da conta deles

Erros do endpoint de token

Os erros seguem a RFC 6749, no formato { "error": "…", "error_description": "…" }: