HTTP API Reference

Complete reference for all Authsome REST endpoints — authentication, users, sessions, MFA, devices, organizations, RBAC, webhooks, and OAuth2.

All endpoints are registered under the configurable BasePath (default /v1/auth) and return JSON. Authentication is via Authorization: Bearer <session_token> header unless noted otherwise. Tenant resolution depends on your Forge middleware configuration.

Authentication

Create a user account and return a session.

Request

{
  "email": "string (required)",
  "password": "string (required)",
  "name": "string",
  "username": "string",
  "app_id": "string",
  "metadata": {}
}

Response 201 Created

{
  "user": {
    "id": "ausr_01j9...",
    "email": "alice@example.com",
    "username": "alice",
    "name": "Alice Liddell",
    "email_verified": false,
    "app_id": "aapp_01j9...",
    "metadata": {},
    "created_at": "2024-11-01T10:00:00Z"
  },
  "session_token": "a3f8c9d4...",
  "refresh_token": "d72b1ef8...",
  "expires_at": "2024-11-01T11:00:00Z"
}

Authenticate with email/username and password.

Request

{
  "email": "string",
  "username": "string",
  "password": "string (required)",
  "app_id": "string"
}

One of email or username is required.

Response 200 OK — same structure as signup response.

If MFA is enabled for the user, returns an MFA challenge instead:

{
  "mfa_required": true,
  "challenge_token": "chall_01jb...",
  "methods": ["totp"],
  "expires_at": "2024-11-01T10:05:00Z"
}

`POST /signout`

Terminate the current session. Requires Authorization header.

Response 200 OK

{"status": "signed out"}

`POST /refresh`

Exchange a refresh token for new session and refresh tokens.

Request

{
  "refresh_token": "string (required)"
}

Response 200 OK

{
  "session_token": "new_token...",
  "refresh_token": "new_refresh...",
  "expires_at": "2024-11-01T12:00:00Z"
}

Password Management

`POST /forgot-password`

Initiate a password reset flow. Always returns success to prevent email enumeration.

Request

{
  "email": "string (required)",
  "app_id": "string"
}

Response 200 OK

{"status": "ok"}

`POST /reset-password`

Reset password using a reset token. Revokes all existing sessions.

Request

{
  "token": "string (required)",
  "new_password": "string (required)"
}

Response 200 OK

{"status": "password reset"}

`POST /change-password`

Change the authenticated user's password. Requires Authorization header.

Request

{
  "current_password": "string (required)",
  "new_password": "string (required)"
}

Response 200 OK

{"status": "password changed"}

`POST /verify-email`

Verify email address with a verification token.

Request

{
  "token": "string (required)"
}

Response 200 OK

{"status": "email verified"}

User Management

`GET /me`

Return the authenticated user's profile. Requires Authorization header.

Response 200 OK — User object.

`PATCH /me`

Update the authenticated user's profile fields. Requires Authorization header.

Request

{
  "name": "string",
  "username": "string",
  "image": "string"
}

Response 200 OK — Updated User object.

`DELETE /me`

Permanently delete the authenticated user's account (GDPR right to erasure). Requires Authorization header.

Response 200 OK

{"status": "account deleted"}

{
  "sessions": [
    {
      "id": "ases_01j9...",
      "app_id": "aapp_01j9...",
      "user_id": "ausr_01j9...",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "device_id": "adev_01j9...",
      "expires_at": "2024-11-01T11:00:00Z",
      "created_at": "2024-11-01T10:00:00Z"
    }
  ]
}

`DELETE /sessions/:sessionId`

Revoke a specific session by ID. Requires Authorization header.

Response 200 OK

{"status": "revoked"}

Multi-Factor Authentication

`POST /mfa/enroll`

Start MFA enrollment for a method. Requires Authorization header.

Request

{
  "method": "totp | sms",
  "phone": "string (required for sms)"
}

Response 201 Created — Enrollment object with TOTP URI/secret (for TOTP) and recovery codes.

`POST /mfa/verify`

Verify MFA enrollment with a code. Requires Authorization header.

Request

{
  "method": "totp | sms",
  "code": "string (required)"
}

Response 200 OK — Updated enrollment with verified: true.

`POST /mfa/challenge`

Complete an MFA challenge during sign-in.

Request

{
  "challenge_token": "string (required)",
  "method": "totp | sms | recovery",
  "code": "string (required)"
}

Response 200 OK — User object with session tokens.

{
  "phone": "string (required, E.164 format)",
  "app_id": "string"
}

Response 200 OK

{"status": "code_sent", "expires_at": "2024-11-01T10:05:00Z"}

`POST /phone/verify`

Verify OTP and sign in (or sign up if new user).

Request

{
  "phone": "string (required)",
  "code": "string (required)",
  "app_id": "string"
}

Response 200 OK — User object with session tokens.

Devices

`GET /devices`

List all tracked devices for the authenticated user. Requires Authorization header.

Response 200 OK

{
  "devices": [
    {
      "id": "adev_01j9...",
      "name": "Chrome on Mac",
      "type": "desktop",
      "browser": "Chrome",
      "os": "macOS",
      "ip_address": "192.168.1.1",
      "trusted": true,
      "last_seen_at": "2024-11-01T10:00:00Z"
    }
  ]
}

{
  "name": "string (required)",
  "slug": "string (required)",
  "description": "string",
  "parent_id": "string",
  "app_id": "string"
}

Response 201 Created — Role object.

`GET /roles`

List all roles for an app.

Param	Type	Description
`app_id`	string	Filter by application

{
  "action": "string (required)",
  "resource": "string (required)"
}

Response 201 Created — Permission object.

{
  "user_id": "string (required)",
  "org_id": "string (optional)"
}

`POST /roles/:roleId/unassign`

Remove a role assignment from a user.

Request

{
  "user_id": "string (required)"
}

{
  "url": "string (required)",
  "events": ["user.created", "auth.signin"],
  "app_id": "string"
}

Response 201 Created — Webhook object including a generated secret for signature verification.

`GET /webhooks`

List all registered webhooks for an app.

Param	Type	Description
`app_id`	string	Filter by application

`GET /webhooks/:webhookId`

Get webhook details.

`PATCH /webhooks/:webhookId`

Update a webhook's URL, events, or active status.

Request

{
  "url": "string",
  "events": ["string"],
  "active": true
}

{
  "name": "string (required)",
  "slug": "string (required)",
  "app_id": "string",
  "metadata": {}
}

Param	Type	Description
`response_type`	string	`code`
`client_id`	string	OAuth2 client ID
`redirect_uri`	string	Callback URL
`scope`	string	Space-separated scopes
`state`	string	CSRF token
`code_challenge`	string	PKCE challenge
`code_challenge_method`	string	`S256`

`POST /oauth2/token`

Token endpoint for code exchange, client credentials, and refresh.

Authorization Code Exchange

grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...

Client Credentials

grant_type=client_credentials&client_id=...&client_secret=...&scope=...

Refresh Token

grant_type=refresh_token&refresh_token=...&client_id=...

Param	Type	Description
`app_id`	string	Application ID
`form_type`	string	`signup`

{
  "target_user_id": "string (required)",
  "app_id": "string"
}

Response 200 OK — Session tokens for the target user with impersonated_by field set.

Error format

All error responses use a consistent JSON envelope:

{
  "error": "human-readable message",
  "code": "ERROR_CODE"
}

HTTP status	`code`	Cause
`400`	`BAD_REQUEST`	Missing required field, validation error, weak password
`401`	`UNAUTHORIZED`	Invalid credentials, expired session, missing auth header
`403`	`FORBIDDEN`	User is banned, insufficient permissions
`404`	`NOT_FOUND`	User, session, device, webhook, or role not found
`409`	`CONFLICT`	Email already taken, username already taken
`429`	`RATE_LIMITED`	Too many requests (rate limit exceeded)
`500`	`INTERNAL_ERROR`	Store failure, unexpected server error

HTTP API Reference

On this page