Email Auth Endpoints

API reference for all email authentication endpoints. These endpoints allow end users to sign up, sign in, verify their email, and reset their password using email + password credentials.

All endpoints require Content-Type: application/json and an Authorization: Bearer <api_key> header. The project is resolved automatically from the API key.

Signup

Register a new end user with email and password.

Request body

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "email_verified": false
  }
}

Error responses

Signin

Authenticate an existing end user.

Request body

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "email_verified": true
  }
}

Error responses

Verify email

Verify a user's email using a 6-digit OTP code sent to their email after signup.

Request body

Response 200

{
  "success": true,
  "email_verified": true
}

Error responses

OTP codes expire after 5 minutes and are invalidated after 3 failed attempts.

Resend verification

Resend the verification email for an unverified user.

Request body

Response

Always returns 200 with { "success": true } to prevent email enumeration.

Request password reset

Send a password reset email. Always returns 200 regardless of whether the email exists.

Request body

Response

Always 200 with { "success": true }.

Confirm password reset

Set a new password using a valid reset token.

Request body

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "email_verified": true
  }
}

JWT claims

All email auth JWTs include the same claims as OAuth JWTs, plus:

{
  "sub": "user_abc123",
  "email": "user@example.com",
  "name": "Jane Doe",
  "picture": null,
  "provider": "email",
  "email_verified": true,
  "project_id": "proj_xyz",
  "iss": "authgate",
  "exp": 1234567890,
  "iat": 1234567590
}

The provider field is always "email" and email_verified is true or false.

MFA challenge response

When a user with MFA enabled signs in via email, the signin endpoint returns an MFA challenge instead of a JWT:

Response 200 (MFA required)

{
  "mfa_required": true,
  "mfa_challenge": "challenge_token_here",
  "mfa_methods": ["totp", "sms"]
}

Submit the challenge to POST /api/proxy/mfa/verify with the user's MFA code to receive the final JWT and refresh token.

Response 200 (MFA setup required)

If the project requires MFA but the user hasn't enrolled yet:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { ... },
  "mfa_setup_required": true
}

Redirect the user to your MFA setup page to enroll before granting access.

Refresh token

All successful authentication responses now include a refresh_token field:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_abc123...",
  "user": { ... }
}

See Session Management for how to use refresh tokens.

Send magic link

Send a magic link email to the user. If the user does not exist, an account is created automatically. Requires the Magic Link provider to be enabled (independent from the Email provider).

Request body

Response 200

{
  "success": true
}

Error responses

Verify magic link

When the user clicks the magic link, this endpoint validates the token, creates a session JWT, and redirects to your callback URL with the token.

Query parameters

Redirect

{callback_url}?token={jwt_token}

JWT claims

Magic link JWTs include the same claims as other auth JWTs:

{
  "sub": "user_abc123",
  "email": "user@example.com",
  "name": null,
  "picture": null,
  "provider": "magic-link",
  "email_verified": true,
  "project_id": "proj_xyz",
  "iss": "authgate",
  "exp": 1234567890,
  "iat": 1234567590
}

The provider field is always "magic-link" and email_verified is always true.