Auth

The Auth API provides comprehensive authentication and user management capabilities including sign-in, sign-up, profile management, and secure token handling. This RESTful API supports multiple authentication methods including password-based login, OTP verification, and invite-based registration.

Operations Overview

Operation	Description
`auth.signin`	Sign in users with multiple authentication methods
`auth.signup`	Register new user accounts
`auth.signout`	Sign out and invalidate user sessions
`auth.update_profile`	Update user profile information
`auth.update_account`	Update core account details (email, password, username)
`auth.send_otp`	Send OTP codes for various operations
`auth.verify_id_token`	Verify JWT token validity
`auth.refresh_token`	Refresh expired authentication tokens
`auth.settings`	Retrieve authentication configuration
`auth.nonce`	Generate nonce values for OAuth flows

auth.signin

Authenticate users using multiple methods: password, OTP, or invite-based authentication.

{
  "op": "auth.signin",
  "grant_type": "password",
  "email": "user@example.com",
  "password": "securePassword123",
  "aud": "your-audience"
}

{
  "op": "auth.signin",
  "grant_type": "password",
  "email": "user@example.com",
  "password": "securePassword123",
  "otp": "123456",
  "aud": "your-audience"
}

{
  "op": "auth.signin",
  "grant_type": "otp",
  "email": "user@example.com",
  "otp": "123456"
}

{
  "op": "auth.signin",
  "grant_type": "otp",
  "email": "newuser@example.com",
  "otp": "123456",
  "password": "newSecurePassword123",
  "display_name": "John Doe",
  "phone_number": "+1234567890"
}

Parameters

op (string, required): Must be "auth.signin"
grant_type (string, required): Either "password" or "otp"
email (string, required): User's email address
password (string, conditional): Required for password-based authentication
otp (string, conditional): Required for OTP-based authentication
aud (string, optional): Audience parameter for JWT
display_name (string, conditional): Required for invite sign-ins
phone_number (string, optional): For invite sign-ins

Response

{
  "data": {
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "refresh_abc123xyz789",
    "token_type": "bearer",
    "token_info": {
      "ttl": 3600,
      "exp": 1705651200,
      "iat": 1705647600,
      "aud": "your-audience",
      "_userkey": "user_123",
      "project_id": "proj_456"
    },
    "user_profile": {
      "_userkey": "user_123",
      "email": "user@example.com",
      "email_verified": true,
      "display_name": "John Doe",
      "name": "John",
      "surname": "Doe",
      "photo_url": "https://example.com/avatar.jpg",
      "username": "johndoe",
      "aud": "your-audience",
      "roles": ["user"],
      "auth_types": ["email"]
    }
  }
}

Use Cases

Standard Login:

{
  "op": "auth.signin",
  "grant_type": "password",
  "email": "admin@company.com",
  "password": "AdminPassword123"
}

Passwordless Login:

{
  "op": "auth.signin",
  "grant_type": "otp",
  "email": "user@example.com",
  "otp": "987654"
}

auth.signup

Request Body

{
  "op": "auth.signup",
  "email": "newuser@example.com",
  "password": "SecurePassword123!",
  "display_name": "Jane Smith",
  "name": "Jane",
  "surname": "Smith",
  "phone_number": "+1987654321",
  "photo_url": "https://example.com/profile.jpg",
  "metadata": {
    "department": "Engineering",
    "role": "Developer",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  }
}

Parameters

op (string, required): Must be "auth.signup"
email (string, required): Valid email address
password (string, required): User's password
display_name (string, required): Full display name
name (string, optional): First name
surname (string, optional): Last name
phone_number (string, optional): Phone number
photo_url (string, optional): Profile picture URL
metadata (object, optional): Additional user data

Response

{
  "data": {
    "_userkey": "user_789",
    "email": "newuser@example.com",
    "email_verified": false,
    "display_name": "Jane Smith",
    "name": "Jane",
    "surname": "Smith",
    "photo_url": "https://example.com/profile.jpg",
    "username": null,
    "aud": "default",
    "roles": ["user"],
    "auth_types": ["email"]
  }
}

Example Use Cases

Basic Registration:

{
  "op": "auth.signup",
  "email": "student@university.edu",
  "password": "StudentPass2024",
  "display_name": "Alex Johnson"
}

Complete Registration with Metadata:

{
  "op": "auth.signup",
  "email": "employee@company.com",
  "password": "CompanyPass123",
  "display_name": "Sarah Wilson",
  "phone_number": "+1555123456",
  "metadata": {
    "employee_id": "EMP001",
    "start_date": "2024-01-15",
    "team": "Marketing"
  }
}

3. Sign Out

auth.signout

Sign out users and invalidate their current session.

Request Body

{
  "op": "auth.signout",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "aud": "your-audience"
}

Parameters

op (string, required): Must be "auth.signout"
id_token (string, required): Current JWT ID token
aud (string, optional): Audience parameter

Response

{
  "data": {
    "signout": true
  }
}

4. Update Profile

auth.update_profile

Update user profile information such as display name, phone number, photo URL, and metadata.

Request Body

{
  "op": "auth.update_profile",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_abc123xyz789",
  "aud": "your-audience",
  "data": {
    "display_name": "John Smith Jr.",
    "phone_number": "+1555987654",
    "photo_url": "https://example.com/new-avatar.jpg",
    "metadata": {
      "preferences": {
        "theme": "light",
        "language": "en-US"
      },
      "social_links": {
        "linkedin": "https://linkedin.com/in/johnsmith",
        "twitter": "@johnsmith"
      }
    }
  }
}

Parameters

op (string, required): Must be "auth.update_profile"
id_token (string, required): Current JWT ID token
refresh_token (string, required): Current refresh token
aud (string, optional): Audience parameter
data (object, required): Profile data to update
- display_name (string, optional): New display name
- phone_number (string, optional): New phone number
- photo_url (string, optional): New profile picture URL
- metadata (object, optional): Additional user metadata

Response

Returns the same structure as the sign-in response with updated profile information and new tokens.

Example Use Cases

Update Display Name:

{
  "op": "auth.update_profile",
  "id_token": "current_token",
  "refresh_token": "current_refresh",
  "data": {
    "display_name": "Dr. Jane Smith"
  }
}

Update Preferences:

{
  "op": "auth.update_profile",
  "id_token": "current_token",
  "refresh_token": "current_refresh",
  "data": {
    "metadata": {
      "notification_settings": {
        "email": true,
        "push": false,
        "sms": true
      }
    }
  }
}

5. Update Account

auth.update_account

Update core account information including email, password, or username. Requires OTP verification.

Change Email

{
  "op": "auth.update_account",
  "email": "current@example.com",
  "otp": "123456",
  "intent": "change_email",
  "new_email": "newemail@example.com"
}

Change Password

{
  "op": "auth.update_account",
  "email": "user@example.com",
  "otp": "123456",
  "intent": "change_password",
  "new_password": "NewSecurePassword123!"
}

Change Username

{
  "op": "auth.update_account",
  "email": "user@example.com",
  "otp": "123456",
  "intent": "change_username",
  "new_username": "newusername"
}

Parameters

op (string, required): Must be "auth.update_account"
email (string, required): Current email address
otp (string, required): OTP code sent for verification
intent (string, required): One of "change_email", "change_password", or "change_username"
new_email (string, conditional): Required when intent is "change_email"
new_password (string, conditional): Required when intent is "change_password"
new_username (string, conditional): Required when intent is "change_username"

Response

Returns updated authentication tokens and user profile.

Workflow

Send OTP with appropriate intent using auth.send_otp
User receives OTP via email
Call auth.update_account with OTP and new information

6. Send OTP

auth.send_otp

Generate and send OTP codes via email for various authentication operations.

Request Body

{
  "op": "auth.send_otp",
  "email": "user@example.com",
  "intent": "signin",
  "aud": "your-audience"
}

Parameters

op (string, required): Must be "auth.send_otp"
email (string, required): Email address to send OTP to
intent (string, required): Purpose of the OTP
- "signin": For passwordless sign-in
- "invite": For user invitations
- "change_password": For password reset
- "change_email": For email change verification
- "change_username": For username change verification
aud (string, optional): Audience parameter

Response

{
  "data": {
    "otp": true,
    "next_op": "auth.signin"
  }
}

Example Use Cases

Password Reset:

{
  "op": "auth.send_otp",
  "email": "user@example.com",
  "intent": "change_password"
}

User Invitation:

{
  "op": "auth.send_otp",
  "email": "newemployee@company.com",
  "intent": "invite"
}

Passwordless Login:

{
  "op": "auth.send_otp",
  "email": "user@example.com",
  "intent": "signin"
}

7. Verify ID Token

auth.verify_id_token

Verify the validity of a JWT ID token. Typically used by administrators or server-side validation.

Request Body

{
  "op": "auth.verify_id_token",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "aud": "your-audience"
}

Parameters

op (string, required): Must be "auth.verify_id_token"
id_token (string, required): JWT token to verify
aud (string, optional): Expected audience

Response

{
  "_userkey": "user_123",
  "email": "user@example.com",
  "email_verified": true,
  "display_name": "John Doe",
  "name": "John",
  "surname": "Doe",
  "photo_url": "https://example.com/avatar.jpg",
  "username": "johndoe",
  "aud": "your-audience",
  "roles": ["user", "admin"],
  "auth_types": ["email"]
}

8. Refresh Token

auth.refresh_token

Refresh expired authentication tokens using a valid refresh token.

Request Body

{
  "op": "auth.refresh_token",
  "refresh_token": "refresh_abc123xyz789",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Parameters

op (string, required): Must be "auth.refresh_token"
refresh_token (string, required): Valid refresh token
id_token (string, required): Current (possibly expired) ID token

Response

Returns new authentication tokens with the same structure as the sign-in response.

Use Cases

Automatic Token Refresh:

// Check if token is about to expire
if (tokenExpiresIn < 300) { // 5 minutes
  const response = await refreshToken(currentRefreshToken, currentIdToken);
  // Update stored tokens
  localStorage.setItem('id_token', response.data.id_token);
  localStorage.setItem('refresh_token', response.data.refresh_token);
}

9. Authentication Settings

auth.settings

Retrieve public authentication configuration and policies.

Request Body

{
  "op": "auth.settings"
}

Response

{
  "data": {
    "allow_email_signup": true,
    "allow_oauth_signup": false,
    "email_settings": {
      "account_update_verification_method": "otp",
      "authentication_method": "password",
      "enabled": true,
      "password_policy": {
        "LENGTH": [8, 64],
        "LOWERCASE": false,
        "NUMBERS": true,
        "SYMBOLS": true,
        "UPPERCASE": false
      },
      "password_policy_name": "MEDIUM",
      "password_recovery_method": "otp",
      "verify_email_on_signup": false
    },
    "enable_email_provider": true,
    "enable_oauth_providers": false,
    "enabled": true,
    "oauth_providers": {}
  }
}

Configuration Fields

allow_email_signup: Whether email registration is enabled
allow_oauth_signup: Whether OAuth registration is enabled
email_settings: Email authentication configuration
- password_policy: Password requirements
- authentication_method: Login method ("password" or "otp")
- verification methods: How account updates are verified
oauth_providers: Available OAuth providers

10. Generate Nonce

auth.nonce

Generate a nonce value for OAuth authentication flows.

Request Body

{
  "op": "auth.nonce"
}

Response

{
  "data": {
    "nonce": "random_nonce_string_abc123"
  }
}

Use Cases

OAuth Flow Initialization:

// Get nonce for OAuth
const nonceResponse = await fetch('auth.nonce', {
  method: 'POST',
  headers: { 'X-API-KEY': 'your-api-key' },
  body: JSON.stringify({ op: 'auth.nonce' })
});

const { nonce } = nonceResponse.data;
// Use nonce in OAuth redirect URL
const oauthUrl = `https://oauth-provider.com/auth?nonce=${nonce}&...`;

Common Response Fields

User Profile Structure

All endpoints returning user information include these fields:

_userkey: Unique user identifier
email: User's email address
email_verified: Email verification status
display_name: Full display name
name: First name
surname: Last name
photo_url: Profile picture URL
username: Username (if set)
aud: Audience parameter
roles: Array of user roles
auth_types: Authentication methods used

Token Information

Authentication responses include:

id_token: JWT token for API access
refresh_token: Token for refreshing expired ID tokens
token_type: Always "bearer"
token_info: Token metadata including expiration times

Error Responses

All endpoints may return errors with this structure:

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password",
    "details": {
      "field": "password",
      "reason": "incorrect"
    }
  }
}

Common Error Codes

INVALID_CREDENTIALS: Wrong email/password combination
OTP_EXPIRED: OTP code has expired
OTP_INVALID: Incorrect OTP code
EMAIL_ALREADY_EXISTS: Email is already registered
TOKEN_EXPIRED: JWT token has expired
TOKEN_INVALID: Malformed or invalid token
WEAK_PASSWORD: Password doesn't meet policy requirements
RATE_LIMIT_EXCEEDED: Too many requests
EMAIL_NOT_VERIFIED: Operation requires verified email

Security Best Practices

1. Token Management

Store refresh tokens securely (HttpOnly cookies recommended)
Implement automatic token refresh before expiration
Clear tokens on sign-out
Use short-lived ID tokens (1 hour recommended)

2. Password Security

Enforce strong password policies
Implement rate limiting for login attempts
Use HTTPS for all authentication requests
Consider implementing account lockout after failed attempts

3. OTP Security

OTP codes expire after 10 minutes
Limit OTP generation frequency
Use intent-specific OTP codes
Implement rate limiting for OTP requests

4. Profile Updates

Validate all profile data on the client and server
Sanitize metadata to prevent injection attacks
Use appropriate field validation (email format, phone number format)
Log profile changes for audit purposes

Authentication Flows

Standard Email/Password Flow

User submits credentials to auth.signin
Server validates and returns tokens
Client stores tokens securely
Use ID token for API requests
Refresh token before expiration

Passwordless OTP Flow

Send OTP to user via auth.send_otp
User receives OTP via email
Submit OTP via auth.signin with grant_type: "otp"
Server validates OTP and returns tokens

Invite-Based Registration

Admin sends OTP with intent: "invite" via auth.send_otp
New user receives invitation email with OTP
User signs in via auth.signin with OTP, password, and profile data
Account is created and user is authenticated

Account Update Flow

Send OTP with appropriate intent via auth.send_otp
User receives verification email
Submit changes via auth.update_account with OTP
Server validates and applies changes
New tokens are issued if successful

Auth

Operations Overview​

1. Sign In​

Sign In with Email and Password​

Sign In with Email, Password and OTP (Two-Factor)​

Sign In with Email and OTP Only​

Sign In with Invite (First-time Setup)​

Parameters​

Response​

Use Cases​

2. Sign Up​

Request Body​

Parameters​

Response​

Example Use Cases​

3. Sign Out​

Request Body​

Parameters​

Response​

4. Update Profile​

Request Body​

Parameters​

Response​

Example Use Cases​

5. Update Account​

Change Email​

Change Password​

Change Username​

Parameters​

Response​

Workflow​

6. Send OTP​

Request Body​

Parameters​

Response​

Example Use Cases​

7. Verify ID Token​

Request Body​

Parameters​

Response​

8. Refresh Token​

Request Body​

Parameters​

Response​

Use Cases​

9. Authentication Settings​

Request Body​

Response​

Configuration Fields​

10. Generate Nonce​

Request Body​

Response​

Use Cases​

Common Response Fields​

User Profile Structure​

Token Information​

Error Responses​

Common Error Codes​

Security Best Practices​

1. Token Management​

2. Password Security​

3. OTP Security​

4. Profile Updates​

Authentication Flows​

Standard Email/Password Flow​

Passwordless OTP Flow​

Invite-Based Registration​

Account Update Flow​

Operations Overview

1. Sign In

Sign In with Email and Password

Sign In with Email, Password and OTP (Two-Factor)

Sign In with Email and OTP Only

Sign In with Invite (First-time Setup)

Parameters

Response

Use Cases

2. Sign Up

Request Body

Parameters

Response

Example Use Cases

3. Sign Out

Request Body

Parameters

Response

4. Update Profile

Request Body

Parameters

Response

Example Use Cases

5. Update Account

Change Email

Change Password

Change Username

Parameters

Response

Workflow

6. Send OTP

Request Body

Parameters

Response

Example Use Cases

7. Verify ID Token

Request Body

Parameters

Response

8. Refresh Token

Request Body

Parameters

Response

Use Cases

9. Authentication Settings

Request Body

Response

Configuration Fields

10. Generate Nonce

Request Body

Response

Use Cases

Common Response Fields

User Profile Structure

Token Information

Error Responses

Common Error Codes

Security Best Practices

1. Token Management

2. Password Security

3. OTP Security

4. Profile Updates

Authentication Flows

Standard Email/Password Flow

Passwordless OTP Flow

Invite-Based Registration

Account Update Flow