API Reference

Base URL#

https://your-domain.com/api/v1

Authentication Endpoints#

These endpoints authenticate end users of your app. All require a valid clientId.

Register a user#

{
  "success": true,
  "data": {
    "user": { "id": "usr_xxx", "email": "user@example.com", "name": null, "roles": [], "emailVerified": false },
    "tokens": { "accessToken": "eyJ...", "refreshToken": "eyJ...", "expiresIn": 900 }
  }
}

Login#

{
  "success": true,
  "data": { "accessToken": "eyJ...", "refreshToken": "eyJ...", "expiresIn": 900 }
}

Refresh tokens#

Issues a new token pair. The submitted refresh token is immediately invalidated (rotation). Reuse detection revokes all user sessions.

{
  "success": true,
  "data": { "accessToken": "eyJ...", "refreshToken": "eyJ...", "expiresIn": 900 }
}

Logout#

Revokes all refresh tokens for the user. Requires a valid access token in the Authorization header.

curl -X POST /api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>"

Verify email#

Verifies a user's email address using the token sent in the verification email. Called automatically when the user clicks the link in their inbox.

{
  "success": true,
  "data": { "message": "Email verified successfully." }
}

Resend verification email#

Re-sends the verification email. Rate-limited to 3 requests per 15 minutes per IP.

Tenant Endpoints#

These endpoints are for developers managing their apps. Protected routes require a tenant JWT.

Register as developer#

Developer login#

List apps#

Create app#

{
  "success": true,
  "data": {
    "app": { "id": "app_xxx", "clientId": "client_xxx", "name": "My App", "isActive": true },
    "clientSecret": "sas_abc123def456..."
  }
}

Rotate client secret#

Invalidates the current secret and returns a new one. Existing app users are unaffected — only API calls using the old secret will fail.

User Management#

Manage users within a specific app. All endpoints require a tenant Bearer token and an appId parameter scoped to the authenticated tenant.

List users#

{
  "success": true,
  "data": [
    {
      "id": "usr_xxx",
      "email": "user@example.com",
      "name": "Jane Doe",
      "emailVerified": true,
      "isActive": true,
      "roles": ["user"],
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Toggle user status#

Toggles the isActive flag for the specified user. Deactivated users cannot log in and will receive an ACCOUNT_DISABLED error.

Set user roles#

Replaces all current roles for the user in this app with the given array.

Role Management#

Three default roles are created automatically for every new app: owner, admin, and user. You can create additional custom roles.

List roles#

{
  "success": true,
  "data": [
    {
      "id": "role_xxx",
      "name": "editor",
      "description": "Can read and write content",
      "permissions": ["read:profile", "write:profile", "read:users"],
      "userCount": 12
    }
  ]
}

Create role#

{
  "success": true,
  "data": { "id": "role_xxx", "name": "editor", "permissions": [], "userCount": 0 }
}

Update role permissions#

Full replace of permissions for the role. Available permission strings:

read:profile    write:profile
read:users      write:users     delete:users
read:roles      write:roles
read:audit
read:sessions   delete:sessions

Error codes#

All errors follow a consistent shape:

{ "success": false, "error": "Human readable message", "code": "ERROR_CODE" }