Authon — Plataforma universal de autenticación

Referencia de API

Documentación completa de la API REST para el servicio de autenticación de Authon. Todas las solicitudes deben incluir una clave API en el encabezado x-api-key o un token Bearer en Authorization.

URL base

text

https://api.authon.dev

Autenticación

Authon usa dos tipos de claves API según si la solicitud proviene de un navegador o un servidor. Pasa la clave en el encabezado x-api-key o como un token Bearer.

Tipo de clave	Prefijo	Uso
Publicable	pk_live_ / pk_test_	Navegador / SDK de cliente. Segura para exponer.
Secreta	sk_live_ / sk_test_	Solo servidor. Acceso de administrador completo. Nunca exponer.
Bearer	eyJhbGci...	Token de acceso del usuario tras iniciar sesión. TTL de 15 minutos.

bash

# Publishable key — client-side requests
curl https://api.authon.dev/v1/auth/providers \
  -H "x-api-key: pk_live_your_publishable_key"

# Token verification is public; no x-api-key is required
curl https://api.authon.dev/v1/auth/token/verify \
  -H "Authorization: Bearer eyJhbGci..."

# Bearer access token — user requests
curl https://api.authon.dev/v1/auth/me \
  -H "Authorization: Bearer eyJhbGci..."

Endpoints de autenticación

POST/v1/auth/signup

Registro

Registra un nuevo usuario con correo y contraseña. Retorna tokens en caso de éxito.

Auth:x-api-key: pk_live_...

Cuerpo de la solicitud

json

{
  "email": "user@example.com",
  "password": "securepassword",
  "displayName": "Jane Doe"          // optional
}

Respuesta

json

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_8f4a2b1c...",
  "expiresIn": 900,
  "user": {
    "id": "usr_abc123",
    "projectId": "proj_xyz",
    "email": "user@example.com",
    "displayName": "Jane Doe",
    "avatarUrl": null,
    "emailVerified": false,
    "isBanned": false,
    "publicMetadata": null,
    "signInCount": 0,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:30:00.000Z"
  }
}

POST/v1/auth/signin

Inicio de sesión

Autentica a un usuario existente con correo y contraseña.

Auth:x-api-key: pk_live_...

Cuerpo de la solicitud

json

{
  "email": "user@example.com",
  "password": "securepassword"
}

Respuesta

json

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_8f4a2b1c...",
  "expiresIn": 900,
  "user": { ... }
}

POST/v1/auth/signout

Cierre de sesión

Revoca la sesión actual e invalida el token de actualización. Requiere token de acceso Bearer.

Auth:Authorization: Bearer <access_token>

Respuesta

json

{
  "success": true
}

POST/v1/auth/token/refresh

Actualizar token

Intercambia un token de actualización por un nuevo token de acceso. Los tokens de acceso expiran después de 15 minutos.

Auth:x-api-key: pk_live_...

Cuerpo de la solicitud

json

{
  "refreshToken": "rt_8f4a2b1c..."
}

Respuesta

json

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900
}

GET/v1/auth/token/verify

Verificar token

Verifica un token de acceso y retorna el usuario asociado. Usado por tu servidor para autenticar solicitudes entrantes.

Auth:Authorization: Bearer <access_token>

Respuesta

json

{
  "valid": true,
  "payload": {
    "sub": "usr_abc123",
    "projectId": "proj_xyz",
    "type": "access",
    "iat": 1767225600,
    "exp": 1767226500
  },
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "displayName": "Jane Doe",
    "avatarUrl": null,
    "emailVerified": true
  }
}

GET/v1/auth/me

Obtener usuario actual

Retorna el perfil del usuario actualmente autenticado.

Auth:Authorization: Bearer <access_token>

Respuesta

json

{
  "id": "usr_abc123",
  "projectId": "proj_xyz",
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "avatarUrl": "https:0
  6: null,
  7: true,
  8: false,
  9: false,
  10: {},
  11: "2026-01-15T10:30:00.000Z",
  "signInCount": 42,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

PATCH/v1/auth/me

Actualizar usuario actual

Actualiza campos del perfil del usuario actualmente autenticado. Solo se actualizan los campos proporcionados.

Auth:Authorization: Bearer <access_token>

Cuerpo de la solicitud

json

{
  "displayName": "Jane Smith",          // optional
  "avatarUrl": "https://example.com/avatar.png"  // optional
}

Respuesta

json

{
  "id": "usr_abc123",
  "displayName": "Jane Smith",
  "avatarUrl": "https://example.com/avatar.png",
  ...
}

Endpoints OAuth

GET/v1/auth/providers

Listar proveedores

Retorna la lista de proveedores OAuth habilitados para el proyecto.

Auth:x-api-key: pk_live_...

Respuesta

json

{
  "providers": ["google", "github", "kakao"]
}

GET/v1/auth/oauth/:provider/url

Obtener URL OAuth

Genera una URL de autorización para el proveedor OAuth indicado. Úsala para redirigir al usuario o abrir una ventana emergente.

Auth:x-api-key: pk_live_...

Respuesta

json

{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}

POST/v1/auth/oauth/callback

Callback OAuth

Intercambia un código de autorización OAuth por tokens de Authon. Llamado por el SDK después de que la ventana emergente retorna.

Auth:x-api-key: pk_live_...

Cuerpo de la solicitud

json

{
  "provider": "google",
  "code": "4/0AX4XfWh...",
  "state": "random_state_string",
  "codeVerifier": "pkce_verifier"   // required if PKCE was used
}

Respuesta

json

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "rt_...",
  "expiresIn": 900,
  "user": { ... }
}

Identidad de marca

GET/v1/auth/branding

Obtener identidad de marca

Retorna la configuración de identidad de marca del proyecto. Usado por el SDK de JS para dar estilo al modal de inicio de sesión.

Auth:x-api-key: pk_live_...

Respuesta

json

{
  "brandName": "Acme Corp",
  "primaryColorStart": "#7c3aed",
  "primaryColorEnd": "#4f46e5",
  "lightBg": "#ffffff",
  "lightText": "#111827",
  "darkBg": "#0f172a",
  "darkText": "#f1f5f9",
  "borderRadius": 12,
  "showEmailPassword": true,
  "showDivider": true,
  "termsUrl": "https:0
  13: "https://acme.com/privacy",
  "logoDataUrl": "data:image/png;base64,..."
}

Códigos de error

Todas las respuestas de error siguen una estructura consistente con un código de estado HTTP y un cuerpo JSON:

json

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

Estado	Error	Descripción
400	Bad Request	Cuerpo de solicitud faltante o malformado
401	Unauthorized	Clave API / token faltante, inválido o expirado
403	Forbidden	La clave es válida pero carece de permiso para esta acción
404	Not Found	El recurso solicitado no existe
409	Conflict	El correo ya está registrado
422	Unprocessable Entity	Validación fallida — revisa los requisitos de los campos
429	Too Many Requests	Límite de velocidad excedido — reintenta después del retraso indicado
500	Internal Server Error	Error inesperado del lado del servidor