Auth

Overview

Auth - Complete authentication system with sign-up, sign-in, profile management, and secure token handling. Supports password-based and passwordless (OTP) authentication methods.

Operations

An operation is an action performed for user authentication or account management. All operations require the op property to specify which operation to perform.

Operation	Description
`auth.signin`	Sign in users with password or OTP
`auth.signup`	Register new user accounts
`auth.signout`	Sign out and invalidate sessions
`auth.send_otp`	Send OTP codes via email
`auth.refresh_token`	Refresh expired tokens
`auth.update_profile`	Update user profile information
`auth.update_account`	Update email, password, or username
`auth.verify_id_token`	Verify JWT token validity
`auth.settings`	Get authentication configuration

Authenticate users and get access tokens. Supports multiple authentication methods.

Password-based sign in:

json

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

OTP-based sign in (passwordless):

json

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

Two-factor authentication:

json

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

Response:

json

{
  "data": {
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "refresh_abc123xyz789",
    "token_type": "bearer",
    "token_info": {
      "ttl": 3600,
      "exp": 1705651200,
      "_userkey": "user_123"
    },
    "user_profile": {
      "_userkey": "user_123",
      "email": "user@example.com",
      "email_verified": true,
      "display_name": "John Doe",
      "roles": ["user"],
      "auth_types": ["email"]
    }
  }
}

json

{
  "op": "auth.signup",
  "email": "newuser@example.com",
  "password": "SecurePassword123",
  "display_name": "Jane Smith",
  "name": "Jane",
  "surname": "Smith",
  "phone_number": "+1234567890",
  "metadata": {
    "department": "Engineering",
    "preferences": {
      "theme": "dark"
    }
  }
}

Required fields:

email - Valid email address
password - User's password (must meet password policy)
display_name - Full display name

Optional fields:

name - First name
surname - Last name
phone_number - Phone number
photo_url - Profile picture URL
metadata - Additional custom data

Response:

json

{
  "data": {
    "_userkey": "user_789",
    "email": "newuser@example.com",
    "email_verified": false,
    "display_name": "Jane Smith",
    "name": "Jane",
    "surname": "Smith",
    "roles": ["user"],
    "auth_types": ["email"]
  }
}

Sign Out

auth.signout

Sign out users and invalidate their current session.

json

{
  "op": "auth.signout",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

json

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

Update Profile

auth.update_profile

Update user profile information without changing core account details (email, password, username).

json

{
  "op": "auth.update_profile",
  "id_token": "current_id_token",
  "refresh_token": "current_refresh_token",
  "data": {
    "display_name": "John Smith Jr.",
    "phone_number": "+1555987654",
    "photo_url": "https://example.com/avatar.jpg",
    "metadata": {
      "preferences": {
        "theme": "light",
        "language": "en-US"
      }
    }
  }
}

Updatable fields:

display_name - Display name
phone_number - Phone number
photo_url - Profile picture URL
metadata - Custom user data

Response: Returns updated user profile with new authentication tokens.

Update Account

auth.update_account

Update core account information (email, password, username). Requires OTP verification.

Change email:

json

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

Change password:

json

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

Change username:

json

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

Required fields:

email - Current email address
otp - OTP code (from auth.send_otp)
intent - One of: change_email, change_password, change_username
Intent-specific field (new_email, new_password, or new_username)

Workflow:

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

Send OTP

auth.send_otp

Generate and send one-time password codes via email for various operations.

json

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

Intent types:

signin - Passwordless sign-in
invite - User invitation
change_password - Password reset
change_email - Email change verification
change_username - Username change verification

Response:

json

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

Common flows:

Passwordless login:

json

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

// 2. Sign in with OTP
{ "op": "auth.signin", "grant_type": "otp", "email": "user@example.com", "otp": "123456" }

Password reset:

json

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

// 2. Update password
{ "op": "auth.update_account", "email": "user@example.com", "otp": "123456", "intent": "change_password", "new_password": "NewPass123" }

Token Management

auth.verify_id_token

Verify JWT token validity.

json

{
  "op": "auth.verify_id_token",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

json

{
  "_userkey": "user_123",
  "email": "user@example.com",
  "email_verified": true,
  "display_name": "John Doe",
  "roles": ["user"],
  "auth_types": ["email"]
}

auth.refresh_token

Refresh expired authentication tokens.

json

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

Response: Returns new id_token and refresh_token with updated expiration times.

Authentication Settings

auth.settings

Get public authentication configuration and password policies.

json

{
  "op": "auth.settings"
}

Response:

json

{
  "data": {
    "allow_email_signup": true,
    "email_settings": {
      "enabled": true,
      "authentication_method": "password",
      "password_policy": {
        "LENGTH": [8, 64],
        "NUMBERS": true,
        "SYMBOLS": true,
        "UPPERCASE": false,
        "LOWERCASE": false
      },
      "password_policy_name": "MEDIUM",
      "verify_email_on_signup": false
    }
  }
}

Configuration includes:

Email signup availability
Password requirements
Authentication methods
Email verification settings

User Profile Structure

All operations returning user information include these fields:

_userkey - Unique user identifier (UUID)
email - User's email address
email_verified - Email verification status (boolean)
display_name - Full display name
name - First name (optional)
surname - Last name (optional)
username - Username (optional)
photo_url - Profile picture URL (optional)
phone_number - Phone number (optional)
roles - Array of user roles
auth_types - Authentication methods used
metadata - Custom user data (optional)

Token Information

Authentication responses include tokens with metadata:

id_token - JWT token for API authentication (expires in 1 hour)
refresh_token - Token for refreshing expired ID tokens
token_type - Always bearer
token_info - Token metadata:
- ttl - Time to live in seconds
- exp - Expiration timestamp
- iat - Issued at timestamp
- _userkey - User identifier

Using tokens:

javascript

// Store tokens securely
localStorage.setItem('id_token', response.data.id_token);
localStorage.setItem('refresh_token', response.data.refresh_token);

// Use id_token in API requests
const headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your_api_key',
  'Authorization': `Bearer ${id_token}`
};

Common Workflows

javascript

// 1. Sign up
await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key'
  },
  body: JSON.stringify({
    op: 'auth.signup',
    email: 'user@example.com',
    password: 'SecurePass123',
    display_name: 'John Doe'
  })
});

// 2. Sign in
const response = await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key'
  },
  body: JSON.stringify({
    op: 'auth.signin',
    grant_type: 'password',
    email: 'user@example.com',
    password: 'SecurePass123'
  })
});

const { id_token, refresh_token } = response.data;

Passwordless Authentication

javascript

// 1. Request OTP
await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key'
  },
  body: JSON.stringify({
    op: 'auth.send_otp',
    email: 'user@example.com',
    intent: 'signin'
  })
});

// 2. User receives OTP via email

// 3. Sign in with OTP
const response = await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key'
  },
  body: JSON.stringify({
    op: 'auth.signin',
    grant_type: 'otp',
    email: 'user@example.com',
    otp: '123456'
  })
});

Token Refresh

javascript

// Check if token is expiring soon
const tokenExpiresIn = tokenInfo.exp - Math.floor(Date.now() / 1000);

if (tokenExpiresIn < 300) { // Less than 5 minutes
  const response = await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'your_api_key'
    },
    body: JSON.stringify({
      op: 'auth.refresh_token',
      refresh_token: currentRefreshToken,
      id_token: currentIdToken
    })
  });

  // Update stored tokens
  localStorage.setItem('id_token', response.data.id_token);
  localStorage.setItem('refresh_token', response.data.refresh_token);
}

Error Handling

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Common error codes:

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

Security Best Practices

Token Security

Store tokens securely (HttpOnly cookies recommended for web apps)
Implement automatic token refresh before expiration
Clear tokens on sign-out
Never expose tokens in URLs or logs

Password Security

Enforce strong password policies via settings
Use HTTPS for all authentication requests
Implement rate limiting on sign-in attempts
Consider implementing account lockout after failed attempts

OTP Security

OTP codes expire after 10 minutes
Each OTP is single-use
Limit OTP generation frequency to prevent abuse
Use intent-specific OTP codes

Profile Updates

Validate all profile data on client and server
Sanitize metadata to prevent injection attacks
Require OTP verification for sensitive changes
Log important account changes for audit purposes

Auth ​

Overview ​

Operations ​

Sign In ​

auth.signin ​

Sign Up ​

auth.signup ​

Sign Out ​

auth.signout ​

Update Profile ​

auth.update_profile ​

Update Account ​

auth.update_account ​

Send OTP ​

auth.send_otp ​

Token Management ​

auth.verify_id_token ​

auth.refresh_token ​

Authentication Settings ​

auth.settings ​

User Profile Structure ​

Token Information ​

Common Workflows ​

Standard Sign Up and Sign In ​

Passwordless Authentication ​

Token Refresh ​

Error Handling ​

Security Best Practices ​

Token Security ​

Password Security ​

OTP Security ​

Profile Updates ​

Auth

Overview

Operations

Sign In

auth.signin

Sign Up

auth.signup

Sign Out

auth.signout

Update Profile

auth.update_profile

Update Account

auth.update_account

Send OTP

auth.send_otp

Token Management

auth.verify_id_token

auth.refresh_token

Authentication Settings

auth.settings

User Profile Structure

Token Information

Common Workflows

Standard Sign Up and Sign In

Passwordless Authentication

Token Refresh

Error Handling

Security Best Practices

Token Security

Password Security

OTP Security

Profile Updates