Autenticación y tokens de API

Rankion autentica las llamadas a la API exclusivamente mediante Bearer Tokens de Laravel Sanctum. No hay auth por cookie, no hay Basic Auth y no hay API keys sin token. Cada token está vinculado a un único usuario en un único team.

Crear un token

Los tokens se emiten desde la interfaz web — Rankion muestra el token en claro una sola vez, después solo queda el valor hasheado en la BD.

1. Inicia sesión en rankion.ai.
2. Abre Settings → API Tokens (enlace directo: /settings/api-tokens).
3. Pulsa «Crear nuevo token», indica un nombre descriptivo (p. ej. local-dev, n8n-prod, claude-code) y opcionalmente una fecha de expiración.
4. Copia el token inmediatamente a tu gestor de contraseñas o al .env de tu aplicación. Una vez cerrado el diálogo, ya no estará visible.

RANKION_API_TOKEN=ranKion_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usar el token

Cada request necesita dos headers:

Authorization: Bearer <tu-token>
Accept: application/json

En POST/PUT/PATCH añade Content-Type: application/json.

Ejemplo curl

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"

# GET — listar proyectos
curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     "$BASE/projects"

# POST — nuevo proyecto
curl -X POST "$BASE/projects" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"name":"My Site","domain":"example.com"}'

Ejemplo de response

{
  "data": {
    "id": 42,
    "name": "My Site",
    "domain": "example.com",
    "team_id": 7,
    "created_at": "2026-05-01T08:30:00Z"
  }
}

Team-Scoping

Cada token de Sanctum está scope al team. En concreto, esto significa:

• El token «conoce» el team del usuario en el momento de su creación.
• Todos los endpoints filtran recursos por team_id. Si intentas leer o mutar un recurso de otro team, la API responde con 403 Forbidden (sin fugas en el body — la existencia no se revela).
• En el endpoint Image Gallery y algunos otros, el cross-team se responde incluso con 404, para que ni siquiera se filtre la existencia de un ID ajeno.
• Si el usuario pertenece a varios teams y cambia de team, los nuevos tokens se vinculan al team activo. Los tokens existentes mantienen su scope original.

Rotar / revocar tokens

Los tokens no tienen «refresh» integrado. La rotación es un proceso de dos pasos:

1. Crea un nuevo token en /settings/api-tokens.
2. Cambia el cliente/job al nuevo token.
3. Revoca el antiguo con el botón «Eliminar» de la misma página — desde ese clic, todas las requests con el token antiguo devuelven 401 Unauthenticated.

Ante una sospecha de fuga: revoca de inmediato y luego emite uno nuevo. La operación es destructiva pero segura — los jobs asíncronos en curso (p. ej. una generación de artículo) no se ven afectados, ya que se ejecutan internamente en el servidor.

Buenas prácticas

• Nunca commits en el frontend. Los tokens son credenciales puramente server-side. En código de navegador quedarían expuestos — las llamadas públicas hazlas a través de tu propio backend proxy.
• Un token por integración. Separa n8n-prod, vercel-cron, claude-code-local. Si se filtra uno, solo revocas ese sin tocar los demás.
• Variables de entorno en lugar de hardcoding. process.env.RANKION_API_TOKEN / getenv('RANKION_API_TOKEN') — nunca como string en el repo.
• Configura fecha de expiración para tokens temporales (p. ej. desarrollo local, migraciones puntuales).
• Nada de tokens en logs. Redacta el header Authorization al loguear requests.
• Solo HTTPS. Rankion no acepta llamadas HTTP — sin TLS el token quedaría comprometido al instante.

Códigos de error de la capa Auth

Continúa con Créditos y rate limits.