Authentication

DYPAI provides a complete authentication and authorization system with multiple sign-in providers, JWT-based sessions, role-based access control, and deep integration with Row Level Security.

Overview

Every DYPAI project includes a built-in auth system that handles user registration, login, token management, and access control. Key capabilities include:

• Multiple providers — email/password, magic links, SMS/OTP, and OAuth with Google, GitHub, Microsoft, and Apple.
• JWT sessions — stateless tokens that encode the user's identity and role, used to authenticate every API request.
• Role-based access control (RBAC) — assign roles with fine-grained permissions in the format resource:action.
• RLS integration — use auth.uid() and auth.role() directly inside PostgreSQL Row Level Security policies.
• Password recovery — built-in reset flow with customizable email templates.

Authentication Flow

The authentication flow follows a standard JWT pattern:

1. The client sends credentials (email + password, OAuth code, or OTP) to the login endpoint.
2. DYPAI validates the credentials against the user store.
3. On success, a short-lived access token (JWT) and a long-lived refresh token are returned.
4. The client includes the access token in the Authorization header of subsequent API requests.
5. When the access token expires, the client uses the refresh token to obtain a new pair.

Here is an example of the login request and response using the email/password provider:

// Login request
const response = await fetch('https://my-project.dypai.ai/auth/v1/token?grant_type=password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_ANON_KEY',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securepassword123',
  }),
})

const session = await response.json()
// {
//   "access_token": "eyJhbGciOiJIUzI1NiIs...",
//   "token_type": "bearer",
//   "expires_in": 3600,
//   "refresh_token": "v1.MjQ1NjcxMjM...",
//   "user": {
//     "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
//     "email": "user@example.com",
//     "role": "authenticated"
//   }
// }

Supported Providers

DYPAI supports the following authentication providers. Enable or disable each provider from the Auth > Providers section in your project dashboard.

See the Providers guide for step-by-step setup instructions for each OAuth provider.

User States

Every user in your project is in one of the following states. The state determines whether the user can authenticate and what access they have:

Role-Based Access Control

DYPAI uses a permission model based on roles. Each role contains a set of permissions in the format resource:action. When a user makes an API request, DYPAI checks whether their role grants the required permission for the requested resource and action.

Default Roles

You can create custom roles with specific permissions. Here is an example of a role definition for a content editor:

{
  "role": "editor",
  "permissions": [
    "posts:read",
    "posts:write",
    "posts:delete",
    "comments:read",
    "comments:write",
    "media:read",
    "media:upload"
  ]
}

Assign roles to users through the dashboard or programmatically via the admin API:

// Assign a custom role to a user
await fetch('https://my-project.dypai.ai/auth/v1/admin/users/USER_ID', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer SERVICE_ROLE_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    role: 'editor',
  }),
})

Row Level Security

DYPAI's auth system integrates directly with PostgreSQL Row Level Security. Inside RLS policies, you can reference the authenticated user's ID and role using built-in helper functions:

-- Only allow users to read their own profiles
CREATE POLICY "Users read own profile"
  ON profiles
  FOR SELECT
  USING (auth.uid() = user_id);

-- Only allow editors to insert posts
CREATE POLICY "Editors can create posts"
  ON posts
  FOR INSERT
  WITH CHECK (auth.role() = 'editor');

Security Best Practices

Follow these recommendations to keep your application secure:

• Use httpOnly cookies for token storage. This prevents JavaScript from accessing tokens and protects against XSS attacks. DYPAI provides cookie-based session management as a built-in option.
• Enable token rotation. When a refresh token is used, the old token is invalidated and a new one is issued. This limits the window of exposure if a refresh token is compromised.
• Keep access tokens short-lived. The default expiration is 1 hour. You can reduce it to as low as 5 minutes for high-security applications in Auth > Settings > Token Lifetime.
• Always enable RLS on tables with user data. Without RLS, any authenticated user can potentially read or modify all rows in a table through the auto-generated API.
• Never expose the service_role key on the client. This key bypasses all RLS policies. It should only be used in server-side code or admin scripts.
• Require email confirmation. Enable the Confirm email setting to prevent users from logging in before verifying their email address.
• Set strong password requirements. Configure minimum password length and complexity rules in Auth > Settings > Password Policy.

Next steps

• Users — manage users, invite flows, and profile metadata
• Roles — create custom roles and configure permissions
• Providers — set up OAuth with Google, GitHub, Microsoft, and Apple