Authon — Plataforma universal de autenticação

Referência da API

Documentação completa da REST API para o serviço de autenticação Authon. Todas as requisições devem incluir uma chave de API no cabeçalho x-api-key ou um Bearer token em Authorization.

URL Base

text

https://api.authon.dev

Autenticação

O Authon usa dois tipos de chaves de API dependendo se a requisição é feita pelo navegador ou pelo servidor. Passe a chave no cabeçalho x-api-key ou como Bearer token.

Tipo de Chave	Prefixo	Uso
Publicável	pk_live_ / pk_test_	Navegador / SDK cliente. Seguro para expor.
Secreta	sk_live_ / sk_test_	Somente servidor. Acesso administrativo completo. Nunca exponha.
Bearer	eyJhbGci...	Token de acesso do usuário após o login. 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 Autenticação

POST/v1/auth/signup

Cadastro

Registre um novo usuário com e-mail e senha. Retorna tokens em caso de sucesso.

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

Corpo da Requisição

json

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

Resposta

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

Login

Autentique um usuário existente com e-mail e senha.

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

Corpo da Requisição

json

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

Resposta

json

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

POST/v1/auth/signout

Logout

Revogue a sessão atual e invalide o token de atualização. Requer Bearer token de acesso.

Auth:Authorization: Bearer <access_token>

Resposta

json

{
  "success": true
}

POST/v1/auth/token/refresh

Atualizar Token

Troque um token de atualização por um novo token de acesso. Os tokens de acesso expiram após 15 minutos.

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

Corpo da Requisição

json

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

Resposta

json

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

GET/v1/auth/token/verify

Verificar Token

Verifique um token de acesso e retorne o usuário associado. Usado pelo seu servidor para autenticar requisições recebidas.

Auth:Authorization: Bearer <access_token>

Resposta

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

Obter Usuário Atual

Retorne o perfil do usuário atualmente autenticado.

Auth:Authorization: Bearer <access_token>

Resposta

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

Atualizar Usuário Atual

Atualize campos do perfil do usuário atualmente autenticado. Apenas os campos fornecidos são atualizados.

Auth:Authorization: Bearer <access_token>

Corpo da Requisição

json

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

Resposta

json

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

Endpoints OAuth

GET/v1/auth/providers

Listar Provedores

Retorne a lista de provedores OAuth habilitados para o projeto.

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

Resposta

json

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

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

Obter URL OAuth

Gere uma URL de autorização para o provedor OAuth especificado. Use isso para redirecionar o usuário ou abrir um popup.

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

Resposta

json

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

POST/v1/auth/oauth/callback

Callback OAuth

Troque um código de autorização OAuth por tokens do Authon. Chamado pelo SDK após o retorno do popup.

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

Corpo da Requisição

json

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

Resposta

json

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

Branding

GET/v1/auth/branding

Obter Branding

Retorne a configuração de branding para o projeto. Usada pelo SDK JS para estilizar o modal de login.

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

Resposta

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 Erro

Todas as respostas de erro seguem um formato consistente com um código de status HTTP e um corpo JSON:

json

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

Status	Erro	Descrição
400	Bad Request	Corpo da requisição ausente ou malformado
401	Unauthorized	Chave de API / token ausente, inválido ou expirado
403	Forbidden	A chave é válida, mas não tem permissão para esta ação
404	Not Found	O recurso solicitado não existe
409	Conflict	O e-mail já está cadastrado
422	Unprocessable Entity	Validação falhou — verifique os requisitos dos campos
429	Too Many Requests	Limite de taxa excedido — tente novamente após o atraso indicado
500	Internal Server Error	Erro inesperado no servidor