Auth Flows

This guide helps you choose the right authentication pattern for your HeroMate app.

Use it when deciding:

• whether users can self-register
• whether access should be invite-only
• when to use jwt endpoints
• when to use api_key endpoints
• how to structure frontend vs server calls

Core Rule

In HeroMate, application-facing HTTP endpoints should use one of these modes:

• jwt: request is tied to a signed-in user
• api_key: request is tied to the project key, usually from server-side code

Do not design public unauthenticated endpoints.

Quick Decision Table

Flow 1: Public App With User Registration

Use this when:

• users create their own accounts
• the app has login, profile, dashboard, or user-owned data
• workflows need current_user or current_user_id

Recommended setup:

1. Enable signup in Auth.
2. Keep email confirmation enabled unless there is a strong reason not to.
3. Use dypai.auth.signUp() and dypai.auth.signInWithPassword() from the app.
4. Protect business endpoints with auth_mode: "jwt".
5. Use allowed_roles only when you need role-based restrictions.

Typical example:

• Marketing site
• SaaS app
• Customer dashboard

const dypai = createClient(process.env.NEXT_PUBLIC_DYPAI_URL!);

await dypai.auth.signUp({
  email,
  password,
  full_name,
});

Use jwt for app screens and user actions:

const { data } = await dypai.api.get('get_profile');

Flow 2: Private App Without Open Registration

Use this when:

• users should not create accounts on their own
• your team decides who gets access
• this is a client project, internal dashboard, partner portal, or staff tool

Recommended setup:

1. Do not expose self-service signup in the UI.
2. Create users from admin/backend flows.
3. Send invite links or recovery-style onboarding links.
4. Let the user set their password in your app.
5. Keep application endpoints in jwt mode.

Typical example:

• company backoffice
• client-specific private app
• invited-only B2B product

Recommended onboarding:

1. Admin creates or invites the user.
2. User opens an invite link to your app callback route.
3. SDK emits PASSWORD_RECOVERY.
4. Your UI shows a set-password screen.
5. User then works normally with JWT session auth.

dypai.auth.onAuthStateChange((event) => {
  if (event === 'PASSWORD_RECOVERY') {
    // Show set-password screen
  }
});

Flow 3: Admin-Provisioned Internal App

This is a stricter version of the private-app pattern.

Use this when:

• only employees, operators, or internal collaborators can enter
• all accounts are created by your team
• roles matter a lot (admin, editor, viewer, etc.)

Recommended setup:

1. No public signup UI.
2. Users are created by admin.
3. Access to app functionality goes through jwt endpoints.
4. Restrict sensitive endpoints with allowed_roles.

Example role split:

• admin: user and system management
• editor: operational work
• viewer: read-only access

Flow 4: Server-to-Server Or Backend Jobs

Use this when:

• there is no human user session
• a worker, cron job, webhook proxy, or backend process needs to call the engine
• the request should not depend on user identity

Recommended setup:

1. Configure the target endpoint with auth_mode: "api_key".
2. Call it from server-side code only.
3. Send X-API-KEY.
4. Do not expose the key in browser code.

Good places to use it:

• Next.js Route Handlers
• Next.js Server Actions
• Server Components that call backend-only logic
• Node workers
• Python jobs
• cron tasks

const dypai = createClient(
  process.env.DYPAI_URL!,
  process.env.DYPAI_API_KEY
);

await dypai.api.post('sync_data', payload);

Mixed Architecture: UI + Server Jobs

This is very common and usually the cleanest setup.

Pattern:

• browser/app UI uses jwt
• server jobs and backend integrations use api_key

Example split:

• create_order -> jwt
• sync_erp_orders -> api_key

This avoids exposing backend credentials in the client while keeping user-facing flows simple.

What To Avoid

Avoid these patterns:

• using api_key from browser-exposed code
• designing open/public endpoints without auth
• mixing user-specific logic into api_key endpoints
• manually sending user_id when JWT context should provide it
• using api_key for normal UI actions when jwt is the correct model

Recommended By App Type

Consumer / SaaS App

• Signup: yes
• Login: yes
• Main endpoint mode: jwt
• Optional backend endpoints: api_key

Private Client App

• Signup: no
• Invitation/provisioning: yes
• Main endpoint mode: jwt
• Admin onboarding flow: invite/set-password

Internal Operations App

• Signup: no
• Provisioning: admin only
• Main endpoint mode: jwt
• Strong allowed_roles: yes

Background Integration Layer

• Signup: not relevant
• User session: no
• Main endpoint mode: api_key

Practical Recommendation

If you are unsure, start with this:

1. For user-facing app screens, use jwt.
2. For backend-only automation, use api_key.
3. If users should not self-register, remove signup UI and use invite/provisioning flows.

Next Steps