Autenticación y OAuth 2.0

Toda solicitud a la API de Furcata se autentica. Usa una clave de API para llamadas de servidor a servidor, o un token de acceso OAuth 2.0 cuando actúas en nombre de un usuario de Furcata o de un agente de IA.

Dos formas de autenticarte

Clave de API: envía tu clave como el parámetro de consulta key. Ideal para tu propio backend.
Token de acceso OAuth 2.0: envía Authorization: ****** Ideal para apps y agentes que actúan por un usuario.

Todos los endpoints viven bajo la URL base https://api.furcata.com/v0.

Llama a la API con un token de acceso

curl -X GET "https://api.furcata.com/v0/account" \
  -H "Authorization: ******"

Registra tu cliente

Los clientes OAuth se registran dinámicamente, siguiendo el RFC 7591. Envía tus URI de redirección y Furcata devuelve un client_id que puedes usar en el resto del flujo.

redirect_uris (obligatorio): las direcciones a las que Furcata puede devolver al usuario.
client_name: un nombre legible para tu integración, de hasta 256 caracteres.
grant_types: authorization_code y refresh_token.
response_types: code.
token_endpoint_auth_method: none para clientes públicos.
scope: los alcances que solicitas, de hasta 512 caracteres.

Registra un cliente

curl -X POST https://api.furcata.com/v0/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My integration",
    "redirect_uris": ["https://example.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "openid"
  }'

Flujo de código de autorización

El flujo tiene tres pasos. El código de autorización es de un solo uso, así que canjéalo de inmediato.

Envía al usuario a la página de consentimiento con tu client_id y redirect_uri.
Después de que el usuario inicie sesión, canjea el token de Furcata del usuario que inició sesión por un código de autorización.
Canjea el código de autorización por un token de acceso y un token de actualización.

1. Envía al usuario a la página de consentimiento

https://api.furcata.com/v0/auth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&state=xyz&code_challenge=YOUR_CODE_CHALLENGE&code_challenge_method=S256

2. Canjea el inicio de sesión por un código de autorización

curl -X POST https://api.furcata.com/v0/auth/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "https://example.com/callback",
    "id_token": "YOUR_FURCATA_TOKEN",
    "code_challenge": "YOUR_CODE_CHALLENGE",
    "code_challenge_method": "S256",
    "state": "xyz"
  }'

3. Canjea el código por tokens

curl -X POST https://api.furcata.com/v0/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "YOUR_AUTHORIZATION_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "https://example.com/callback",
    "code_verifier": "YOUR_CODE_VERIFIER"
  }'

Actualiza un token de acceso

Los tokens de acceso son de corta duración. Cuando uno expire, canjea tu token de actualización por un par nuevo en lugar de pedirle al usuario que inicie sesión otra vez.

Actualiza un token de acceso

curl -X POST https://api.furcata.com/v0/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID"
  }'

Consulta la sesión actual

Usa el endpoint de sesión para confirmar que un token sigue siendo válido y ver a quién pertenece.

Lee la sesión actual

curl -X GET https://api.furcata.com/v0/auth/session \
  -H "Authorization: ******"

Documentos de descubrimiento

Los clientes y agentes pueden descubrir cómo autenticarse sin ninguna configuración. Estos documentos son públicos.

https://api.furcata.com/v0/.well-known/oauth-authorization-server
https://api.furcata.com/v0/.well-known/oauth-protected-resource
https://api.furcata.com/v0/.well-known/oauth-protected-resource/mcp

Usa PKCE

Envía un code_challenge con code_challenge_method establecido en S256 cuando inicies el flujo, y luego envía el code_verifier correspondiente cuando canjees el código. Protege el código de autorización si alguna vez es interceptado.

Próximos pasos

Lee Errores e idempotencia para aprender cómo se reportan las fallas, y luego Límites de peticiones para ver cuánto puedes enviar. La descripción general de la API REST enumera todos los endpoints.