API reference

The REST API lives under /api/v1. The OAuth and OIDC endpoints live at the root. Every response uses JSON.

Errors

Every error uses one shape.

{
  "error": {
    "code": "invalid_credentials",
    "message": "Email or password is incorrect",
    "details": null
  }
}

The OAuth token endpoint uses the standard OAuth shape instead.

{ "error": "invalid_grant", "error_description": "The code has expired" }

Authentication

Endpoints use one of three schemes.

| Scheme | Header | Used by | | --- | --- | --- | | User token | Authorization: Bearer ACCESS_TOKEN | User actions | | API key | X-Api-Key plus a signature | Server to server calls | | Session cookie | httpOnly cookie | The first party frontend |

Signed server requests

Server to server endpoints need three headers. You sign each request with your API secret.

  • X-Api-Key is your application API key.
  • X-Timestamp is the current unix time. Authly accepts a window of five minutes.
  • X-Signature is a hex HMAC SHA256 over the string timestamp.METHOD.path.body, keyed with your API secret.

Auth endpoints

| Method | Path | Purpose | | --- | --- | --- | | POST | /api/v1/auth/register | Create an account | | POST | /api/v1/auth/login | Sign in with a password | | POST | /api/v1/auth/refresh | Rotate the refresh token | | POST | /api/v1/auth/logout | Revoke the current session | | POST | /api/v1/auth/password/forgot | Send a reset link | | POST | /api/v1/auth/password/reset | Set a new password | | POST | /api/v1/auth/magic-link | Send a sign in link | | POST | /api/v1/auth/magic-link/consume | Sign in with the link | | POST | /api/v1/auth/verify-email | Confirm an email address | | POST | /api/v1/auth/mfa/verify | Complete a second factor |

OAuth and OIDC endpoints

| Method | Path | Purpose | | --- | --- | --- | | GET | /.well-known/openid-configuration | Discovery document | | GET | /.well-known/jwks.json | Public signing keys | | GET | /oauth/authorize | Start a login | | POST | /oauth/token | Exchange a code or refresh token | | GET | /oauth/userinfo | Read the signed in user | | POST | /api/v1/tokens/introspect | Check a token on the server |

Profile endpoints

These need a user token.

| Method | Path | Purpose | | --- | --- | --- | | GET | /api/v1/me | Read the current user | | PATCH | /api/v1/me | Update the name | | PUT | /api/v1/me/avatar | Upload an avatar | | GET | /api/v1/me/emails | List emails | | POST | /api/v1/me/emails | Add an email | | GET | /api/v1/me/sessions | List devices | | DELETE | /api/v1/me/sessions/:id | Revoke a device | | GET | /api/v1/me/login-history | Read the audit trail |

Public profile

Your servers read another user's public profile with a signed request.

GET /api/v1/users/:id/profile

{
  "profile": {
    "sub": "1042",
    "name": "Alice Rahman",
    "avatar_url": "https://...",
    "email": "[email protected]",
    "email_verified": true
  }
}