Authon — Universal Authentication Platform

API Reference

Complete REST API documentation for the Authon authentication service. All requests must include an API key in the x-api-key header or a Bearer token in Authorization.

Base URL

text

https://api.authon.dev

Authentication

Authon uses two types of API keys depending on whether the request is made from a browser or a server. Pass the key in the x-api-key header or as a Bearer token.

Key Type	Prefix	Usage
Publishable	pk_live_ / pk_test_	Browser / client SDK. Safe to expose.
Secret	sk_live_ / sk_test_	Server only. Full admin access. Never expose.
Bearer	eyJhbGci...	User access token from sign-in. 15-minute TTL.

bash

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

# Secret key — server-side admin requests
curl https://api.authon.dev/v1/auth/token/verify \
  -H "x-api-key: sk_live_your_secret_key" \
  -H "Authorization: Bearer eyJhbGci..."

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

Auth Endpoints

POST/v1/auth/signup

Sign Up

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

Request Body

json

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

Response

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

Sign In

Authenticate an existing user with email and password.

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

Request Body

json

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

Response

json

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

POST/v1/auth/signout

Sign Out

Revoke the current session and invalidate the refresh token. Requires Bearer access token.

Auth:Authorization: Bearer <access_token>

Response

json

{
  "success": true
}

POST/v1/auth/token/refresh

Refresh Token

Exchange a refresh token for a new access token. Access tokens expire after 15 minutes.

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

Request Body

json

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

Response

json

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

GET/v1/auth/token/verify

Verify Token

Verify an access token and return the associated user. Used by server SDKs to authenticate incoming requests.

Auth:x-api-key: sk_live_...

Response

json

{
  "id": "usr_abc123",
  "projectId": "proj_xyz",
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "emailVerified": true,
  "isBanned": false,
  "publicMetadata": { "plan": "pro" },
  "signInCount": 42,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

GET/v1/auth/me

Get Current User

Return the profile for the currently authenticated user.

Auth:Authorization: Bearer <access_token>

Response

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

Update Current User

Update profile fields for the currently authenticated user. Only supplied fields are updated.

Auth:Authorization: Bearer <access_token>

Request Body

json

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

Response

json

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

OAuth Endpoints

GET/v1/auth/providers

List Providers

Return the list of OAuth providers enabled for the project.

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

Response

json

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

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

Get OAuth URL

Generate an authorization URL for the given OAuth provider. Use this to redirect the user or open a popup.

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

Response

json

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

POST/v1/auth/oauth/callback

OAuth Callback

Exchange an OAuth authorization code for Authon tokens. Called by the SDK after the popup returns.

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

Request Body

json

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

Response

json

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

Branding

GET/v1/auth/branding

Get Branding

Return the branding configuration for the project. Used by the JS SDK to style the login modal.

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

Response

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,..."
}

Error Codes

All error responses follow a consistent shape with an HTTP status code and a JSON body:

json

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

Status	Error	Description
400	Bad Request	Missing or malformed request body
401	Unauthorized	Missing, invalid, or expired API key / token
403	Forbidden	The key is valid but lacks permission for this action
404	Not Found	The requested resource does not exist
409	Conflict	Email is already registered
422	Unprocessable Entity	Validation failed — check field requirements
429	Too Many Requests	Rate limit exceeded — retry after the indicated delay
500	Internal Server Error	Unexpected server-side error