Sign Up API

Register new user accounts with email/password or OAuth providers. All registration methods follow the same response format for consistency across providers.

Endpoint

POST /api/auth/sign-up

Email/Password Registration

Request

{
  "email": "user@example.com",
  "password": "securePassword123!",
  "name": "John Doe",
  "organizationName": "Acme Inc" // Optional: auto-create org
}

Validation Rules

Field	Rules
`email`	Valid email format, unique
`password`	Min 8 chars, 1 uppercase, 1 number, 1 special char
`name`	2-100 characters
`organizationName`	Optional, 2-100 characters

Success Response (201)

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_123456",
      "email": "user@example.com",
      "name": "John Doe",
      "emailVerified": false,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "session": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expiresAt": "2024-01-15T10:30:00Z"
    },
    "organization": {
      "id": "org_789",
      "name": "Acme Inc",
      "slug": "acme-inc"
    }
  },
  "message": "Account created successfully"
}

Error Responses

Email Already Exists (409)

{
  "success": false,
  "error": {
    "code": "EMAIL_EXISTS",
    "message": "An account with this email already exists"
  }
}

Validation Error (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "password", "message": "Password must contain at least one uppercase letter" }
    ]
  }
}

OAuth Registration

Initiate OAuth flow for social login registration.

Request

{
  "provider": "google",
  "callbackUrl": "/dashboard"
}

Supported Providers

Provider	ID	Notes
Google	`google`	Requires Google OAuth credentials
GitHub	`github`	Public or private email access
GitLab	`gitlab`	Self-hosted options available
Microsoft	`azure-ad`	Enterprise Microsoft accounts
Slack	`slack`	Workspace authentication

Response (200)

{
  "success": true,
  "data": {
    "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=..."
  }
}

Code Examples

cURL

curl -X POST https://api.yourdomain.com/api/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123!",
    "name": "John Doe"
  }'

JavaScript/TypeScript

const response = await fetch('/api/auth/sign-up', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securePassword123!',
    name: 'John Doe'
  })
});

const result = await response.json();

if (result.success) {
  // Store session token
  localStorage.setItem('session_token', result.data.session.token);
  // Redirect to dashboard
  window.location.href = '/dashboard';
}

React Hook Example

import { useState } from 'react';

function useSignUp() {
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const signUp = async (data: {
    email: string;
    password: string;
    name: string;
  }) => {
    setIsLoading(true);
    setError(null);

    try {
      const response = await fetch('/api/auth/sign-up', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      });

      const result = await response.json();

      if (!result.success) {
        throw new Error(result.error.message);
      }

      return result.data;
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Sign up failed');
      throw err;
    } finally {
      setIsLoading(false);
    }
  };

  return { signUp, isLoading, error };
}

Provider-Specific Behavior

BetterAuth

Stores user in local database via Drizzle
Supports email verification flow
Optional auto-organization creation

NextAuth

Uses NextAuth's built-in registration
Database adapter stores user data
Automatic account linking for OAuth

Clerk

Delegates to Clerk's sign-up API
Automatic email verification handling
Built-in bot protection

AuthKit

Uses WorkOS user management
Supports SSO during registration
Enterprise directory sync available

Webhook Events

When a user signs up, the following webhook events are triggered:

Event	Description
`user.created`	New user account created
`organization.created`	If organization was auto-created
`session.created`	User session established

Rate Limits

Email/Password: 5 attempts per IP per hour
OAuth: 20 attempts per IP per hour
Verification emails: 3 per email per hour

On this page