Apps OAuth

1. Registra tu app

Registras tu app tú mismo. Inicia sesión con tu cuenta de Gravl en app.gravl.ai/settings/developer y abre la sección Apps OAuth, junto a tus tokens de acceso personales.

Allí indicas:

• El nombre de tu app y una breve descripción de lo que hace; el nombre no puede contener “Gravl”
• Un logo opcional: un PNG, JPEG o WebP cuadrado (no se admite SVG), de al menos 128×128 px y como máximo 1 MB. Aparece en la pantalla de consentimiento junto al nombre de tu app
• La página web de tu app: una URL https
• Hasta 5 redirect URIs: URLs https absolutas (http://localhost permitido para desarrollo)
• Los scopes que necesita tu app; pide el mínimo, los usuarios ven exactamente lo que solicitas
• El tipo de cliente: confidencial para apps de servidor que pueden guardar un client_secret, o público para apps de navegador o nativas, que no reciben secreto y deben usar PKCE

Recibes un client_id (gci_…) al instante. Los clientes confidenciales reciben también un client_secret (gcs_…, se muestra una sola vez; guárdalo como una contraseña). Puedes rotar el secreto más adelante desde la misma página. Cada cuenta puede tener hasta 5 apps OAuth.

Modo de desarrollo y revisión

Una app nueva empieza en modo de desarrollo. Funciona desde el primer momento, pero solo tu propia cuenta de Gravl puede autorizarla: los demás usuarios ven un aviso en la pantalla de consentimiento y no pueden conectarse. Úsalo para construir y probar todo el flujo.

• Cuando tu app esté lista, pulsa Enviar a revisión. Revisamos el nombre, la descripción, el logo, la página web, las redirect URIs y los scopes, y te enviamos la decisión por email
• Una vez aprobada, cualquier usuario de Gravl puede conectar tu app
• Si la rechazamos, el email y la página de ajustes muestran el motivo; edita la app y vuelve a enviarla
• Las apps aprobadas no se pueden editar desde la página de ajustes, ni siquiera el logo

Para cambiar una app aprobada, o si tienes dudas sobre el registro o la revisión, escribe a developers@gravl.ai.

2. Envía al usuario a la pantalla de consentimiento

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

El usuario inicia sesión con su cuenta de Gravl, ve el nombre de tu app y los scopes solicitados en lenguaje claro, y aprueba; su navegador vuelve a tu redirect_uri con ?code=gac_…&state=… (o error=access_denied si cancela).

• Los códigos llevan el prefijo gac_, son válidos 10 minutos, de un solo uso, y están ligados a tu app y a la redirect_uri para la que se emitieron
• PKCE (S256) es obligatorio para clientes públicos (apps de navegador o nativas, que no tienen client_secret) y muy recomendable para todos
• Verifica siempre que state coincide con lo que enviaste: es tu protección CSRF

Los clientes públicos omiten client_secret en el endpoint de token; PKCE es su autenticación de cliente. Eliges el tipo de cliente al crear la app.

3. Intercambia el 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. Refresca

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_…

La respuesta tiene la misma forma que el intercambio del código. El token de refresco presentado se revoca en la misma transacción: persiste siempre el nuevo refresh_token antes de descartar el antiguo. Reutilizar un token de refresco ya usado devuelve invalid_grant.

5. Revoca

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

• Revocar un token de acceso mata solo ese token
• Revocar un token de refresco revoca el grant completo: todos los tokens vigentes para ese par usuario + app
• Según la RFC 7009 el endpoint devuelve 200 incluso para tokens desconocidos; solo unas credenciales de cliente incorrectas producen un error
• Los usuarios también pueden revocar el acceso de tu app desde su cuenta

Errores del endpoint de token

Los errores siguen la RFC 6749: { "error": "…", "error_description": "…" }: