Authentication

DYPAI provides a complete authentication system out of the box. It handles user registration, login, session management, and integrates deeply with the API Builder to protect your endpoints.

Authentication Methods

Email & Password

The standard way for users to sign up and log in.

• Automatic email confirmation flows.
• Built-in password reset handling.

Passwordless (OTP)

Allow users to sign in without a password using a one-time code sent via SMS (requires Twilio configuration) or email.

OAuth Providers

Let users sign in with their existing accounts. DYPAI supports a wide range of OAuth providers. Each provider needs to be configured with its Client ID and Secret via environment variables in your project's auth configuration.

To use OAuth from the SDK:

// Redirect the user to the OAuth provider
await dypai.auth.signInWithOAuth('google', {
  redirectTo: 'https://yourapp.com/auth/callback',
  scopes: ['email', 'profile']  // optional
});

How Authentication Works

Authentication follows a standard JWT flow:

1. The user signs in using any method (email/password, OTP, or OAuth).
2. The auth engine validates the credentials and returns a JWT access token and a refresh token.
3. Every subsequent API request includes the access token in the Authorization: Bearer <token> header.
4. The engine validates the token and extracts the user's identity (ID, email, and role).
5. When the access token expires, the SDK automatically refreshes it in the background.

JWT Token Structure

When a user authenticates, their JWT contains these key claims:

{
  "sub": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "email": "user@example.com",
  "role": "authenticated",
  "app_metadata": {
    "role": "admin"
  }
}

• role — the standard auth role (always "authenticated" for logged-in users).
• app_metadata.role — the custom app role you assign to the user (e.g. "admin", "editor", "member"). This is the role used by the engine to enforce access control.

Roles & Access Control

DYPAI uses a simple but powerful role-based access control (RBAC) model. Instead of hardcoded permission lists, roles are custom strings that you define and assign to users. The engine then checks these roles against the Allowed Roles configured on each endpoint.

Creating Roles

Roles are stored in the system.roles table of your project's database. You can create them from the Users section in the dashboard, which provides a role management interface. Each role has:

Assigning Roles to Users

A user's role is stored in the raw_app_meta_data column of the auth.users table under the role key. When the user authenticates, this value is embedded in their JWT as app_metadata.role.

You can assign roles through:

• The Users management table in the dashboard.
• The admin API endpoint (requires service role access):

# Assign the "editor" role to a user
curl -X POST https://your-project.dypai.app/api/v0/admin/users/USER_ID/role \
  -H "Authorization: Bearer SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor"}'

Protecting Endpoints

Every endpoint you create in the API Builder has an Authentication Mode setting — either jwt (user session) or api_key (server-to-server).

Access rules:

Example: JWT vs API Key Endpoints

// JWT endpoint (auth_mode = "jwt", allowed_roles = ["admin"])
// The user must be signed in and have the "admin" role
const { data, error } = await dypai.auth.signInWithPassword({
  email: 'admin@example.com',
  password: 'secure-password',
});
await dypai.api.post('delete_user', { user_id: '...' });
// → 403 Forbidden if the user's role is not "admin"

// API Key endpoint (auth_mode = "api_key")
// No user session needed, but requires the project API Key
// Usually called from a backend or a secure script
const products = await dypai.api.get('get_products'); 
// (The SDK automatically attaches the API Key if configured)

Permission System

In addition to controlling access to your endpoints with roles, DYPAI includes a granular permission system for admin operations. Permissions are stored as a JSON object in the permissions field of each role in system.roles.

Available Permissions

permissions Field Structure

The permissions field is a JSONB object where each key is the permission name and the value is true or false:

{
  "manage_users": true,
  "manage_roles": true,
  "manage_system": true
}

By default, the "admin" role is created with all three permissions enabled. The "editor" and "viewer" roles are created without permissions — you can enable them from the dashboard.

How Permission Checking Works

For application builders, the main model is:

1. Signed-in users call jwt endpoints.
2. The engine checks the user's role and permissions.
3. Internal service_role access exists for trusted system/admin operations, but it is not a normal application-facing auth flow.

If the permission is missing or false, the engine returns a 403 Forbidden with the message "Permission 'permission_name' required.".

Managing Permissions from the Dashboard

In the Auth > Roles section of the dashboard, each role displays toggles for the three permissions. You can enable or disable permissions individually for each role without writing any code.

Admin Endpoints and Required Permissions

Example: Custom Role with Permissions

You can create a role like "moderator" that can only manage users but not roles or system:

curl -X POST https://your-project.dypai.app/api/v0/admin/roles \
  -H "Authorization: Bearer SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "moderator",
    "description": "Moderator with user management access",
    "permissions": {
      "manage_users": true,
      "manage_roles": false,
      "manage_system": false
    }
  }'

A user with the "moderator" role will be able to list, create, and delete users, but won't be able to manage roles or view infrastructure status.

API Key Authentication

For server-to-server communication, DYPAI supports API Keys as an alternative to JWT tokens. API Keys are managed in the Access Keys section.

• Send the key in the X-API-KEY header.
• API Keys are only accepted for endpoints configured with auth_mode: "api_key".
• When using an API Key, role-based access control (RBAC) is bypassed.
• Each key has an is_active flag and the engine tracks last_used_at for auditing.

# Call an endpoint configured with auth_mode: "api_key"
curl https://your-project.dypai.app/api/v0/sync_data \
  -H "X-API-KEY: your-api-key"

Authentication Resolution

For application-facing HTTP endpoints, the important rule is:

1. API Key — if the endpoint is in api_key mode, the X-API-KEY header must match a valid project key.
2. JWT Bearer Token — if the endpoint is in jwt mode, a valid user token is required, and the user's role must be in the allowed_roles list.

Internal service_role handling exists for trusted backend/admin operations, but app developers should generally reason in terms of jwt and api_key.

If no valid credentials matching the endpoint's mode are provided, the engine returns a 401 Unauthorized error. Public (unauthenticated) endpoints are not supported for security reasons.

Using Auth with the SDK

The easiest way to integrate authentication is using the DYPAI Client SDK:

import { createClient } from '@dypai-ai/client-sdk';

const dypai = createClient('https://your-project.dypai.app');

// Sign in
const { data, error } = await dypai.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password',
});

// Call a protected endpoint — the SDK automatically attaches the JWT
const products = await dypai.api.get('get_products');

The SDK handles token persistence in localStorage and automatic background refresh. See the full SDK Auth reference for all available methods.

If you need to call backend-only api_key endpoints, initialize a separate server-side client with createClient(url, process.env.DYPAI_API_KEY).

Next Steps

• SDK Auth Reference — all authentication methods available in the client SDK.
• API Builder — create and protect your endpoints.
• API Keys — set up server-to-server authentication.