Authentication
HeroMate includes a complete auth system out of the box. User registration, login, sessions, roles, and JWT — all managed for you.
Choosing your auth pattern
Not sure if you need open signup, invite-only, or OAuth? See Auth Flows.
Auth methods
Email & Password
Standard signup and login with email confirmation and password reset.
OAuth Providers
Social login with the providers you enable under Auth → Providers.
Passwordless (OTP)
Sign in with a code sent via email or SMS. No password needed.
Dashboard sections
The Authentication area (Build → Authentication) is organized into a few sub-sections:
| Section | What it does |
|---|---|
| Users | Browse, create, invite, and manage your app's users. |
| Roles | Define custom roles and assign them to users. |
| Providers | Enable and configure social/OAuth login (Client ID + Secret per provider). |
| Email templates and the sender used for confirmation, recovery, and invites. | |
| SMS | Configure the SMS provider for phone OTP sign-in. |
| Settings | Toggle signup, email confirmation, and other auth behaviors. |
Using auth with the SDK
Auth is built into the SDK — no endpoints needed:
import { createClient } from '@dypai-ai/client-sdk'
const dypai = createClient('https://YOUR_PROJECT_ID.dypai.app')
// Sign up
const { error } = await dypai.auth.signUp({ email, password })
// Sign in
const { error } = await dypai.auth.signInWithPassword({ email, password })
// OAuth
await dypai.auth.signInWithOAuth('google')
// Sign out
await dypai.auth.signOut()
// The SDK auto-attaches JWT to all API calls
const { data } = await dypai.api.get('list_products')
React hooks
import { useAuth } from '@dypai-ai/client-sdk/react'
function LoginPage() {
const { signIn, isLoading, isAuthenticated } = useAuth()
const handleSubmit = async (email, password) => {
const { error } = await signIn(email, password)
if (error) setError(error.message)
}
}
| Parameter | Type | Description |
|---|---|---|
signIn(email, password) | async | Email + password login |
signUp(email, password, data?) | async | Register new user. Returns confirmationRequired if email verification is on |
signOut() | async | Clear session and logout |
resetPassword(email) | async | Send password recovery email |
setPassword(password) | async | Set new password (after recovery/invite link) |
signInWithOAuth(provider) | async | Redirect to OAuth provider (google, github, apple) |
signInWithOtp({ email }) | async | Send magic link or OTP code |
isAuthenticated | boolean | Whether user is logged in |
isLoading | boolean | Auth state still loading |
user | object | null | Current user (id, email, role) |
How it works
- User signs in → auth engine validates credentials → returns JWT + refresh token
- SDK stores tokens and attaches JWT to every API request automatically
- When JWT expires, SDK refreshes in the background — no user interruption
- Endpoints check the JWT role against their allowed_roles list
Roles & access control
Roles are custom strings you define (e.g., admin, editor, viewer). Each endpoint has an allowed_roles list.
| Parameter | Type | Description |
|---|---|---|
jwt mode | Endpoint | User must be signed in + their role must be in allowed_roles |
api_key mode | Endpoint | Requires X-API-KEY header. For server-to-server, not browser |
public mode | Endpoint | No auth required. Only for read-only public data |
Creating roles
Create roles from the dashboard (Auth → Roles) or via MCP:
"Create an admin role with manage_users permission"
Assigning roles to users
Assign from the dashboard (Auth → Users) or via MCP:
"Assign the editor role to user@example.com"
OAuth setup
Each OAuth provider needs a Client ID + Secret configured under Auth → Providers:
| Provider | How to set up |
|---|---|
| Create OAuth credentials in Google Cloud Console | |
| GitHub | Create an OAuth App in GitHub Settings |
| Apple | Requires Apple Developer Program membership |
Enable and configure providers from the dashboard (Auth → Providers) or via MCP with app_settings.
Enable before you call it
signInWithOAuth(provider) only works once the provider is enabled under Auth → Providers. Phone/SMS OTP (signInWithOtp({ phone })) needs an SMS provider configured under Auth → SMS.
Server-side auth: the dypai_auth node
For server-side auth operations inside your workflows — creating users, assigning roles, or validating sessions from an endpoint — use the dypai_auth workflow node in the API Builder. It runs with the engine's privileges, so keep those endpoints in jwt (admin role) or api_key mode and never expose them publicly.