Sign-up

Creates a new user account with email and password authentication. Upon successful registration, the system automatically authenticates the user and returns JWT tokens for immediate API access.

Endpoint

POST /auth/signup

Authentication: Tenant authentication required

Description

The signup endpoint allows users to register a new account. Currently, only the password authentication method is supported for registration. Other authentication methods (Social providers, OTP, guest) cannot be used for signup as they are restricted for this capability.

After successful registration:

• A new user record is created in the system
• An authentication provider is linked to the user
• JWT access and refresh tokens are generated and returned
• The user is immediately authenticated and can use the returned tokens

Request

Body

{
  "method": "password",
  "email": "user@example.com",
  "password": "securepassword123"
}

Parameter	Type	Required	Description	Constraints
method	string	Yes	Authentication method	Must be "password"
email	string	Yes	User's email address	Valid email format
password	string	Yes	User's password	Minimum 8 characters

Response

Status Code: 201 Created

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "accessTokenExpireAt": "2025-01-15T11:30:00.000Z",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshTokenExpireAt": "2025-01-16T10:30:00.000Z",
    "userId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "newUser": true
  }
}

Field	Type	Description
accessToken	string	JWT access token
accessTokenExpireAt	string	Access token expiration timestamp
refreshToken	string	JWT refresh token
refreshTokenExpireAt	string	Refresh token expiration timestamp
userId	string	ULID user identifier
newUser	boolean	Always true

Rate Limiting

Rate limiting is applied to prevent abuse and ensure system stability. The signup endpoint has the following rate limits:

Limit Type	Rate	Window
Per IP	5 requests	1 hour

When rate limits are exceeded, the API returns a 429 Too Many Requests status code.

For information about rate limit headers, see Rate Limiting in the overview.

Errors

For detailed explanations of all error codes, see the Error Codes page where you can find all system errors.

400 Bad Request - Validation Error

Occurs when the request body fails validation. Common causes include invalid email format, password too short, or missing required fields.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "The provided request data is invalid.",
    "code": "VALIDATION_ERROR",
    "status": 400,
    "validation": {
      "email": "Invalid email",
      "password": "String must contain at least 8 character(s)"
    }
  }
}

Field	Error Message	Cause
method	Invalid literal value	Method is not "password"
email	Invalid email	Email format is invalid
password	String must contain at least 8 character(s)	Password is less than 8 characters

403 Forbidden - Restricted Capability

Occurs in two scenarios:

1. Method restriction: Attempting to use an authentication method that is restricted for the signup capability. Only the password method is allowed for signup.

2. Tenant configuration: The system administrator for the tenant has disabled password-based signup. Existing users can still sign in, but new user registrations via email/password are not accepted.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Capability signup is restricted",
    "code": "RESTRICTED_CAPABILITY",
    "status": 403
  }
}

Restricted methods: facebook, google, apple, otp, guest

409 Conflict - User Already Exists

Occurs when a user with the same email address already exists in the system.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "User already exists",
    "code": "USER_ALREADY_EXISTS",
    "status": 409
  }
}

429 Too Many Requests - Rate Limit Exceeded

Occurs when the rate limit is exceeded. See Rate Limiting section for details.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Too many requests",
    "code": "TOO_MANY_REQUESTS",
    "status": 429
  }
}

500 Internal Server Error

Occurs when an internal error happens during user creation. Common causes include missing provider ID after authentication method processing or other unexpected system state.

Error codes:

• UNEXPECTED_STATE - Unexpected system state (e.g., missing provider ID)
• INTERNAL_SERVER - General internal server error

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Missing provider ID",
    "code": "UNEXPECTED_STATE",
    "status": 500
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Something went wrong on our side.",
    "code": "INTERNAL_SERVER",
    "status": 500
  }
}

Notes

• The email address is used as the provider ID for password authentication
• After successful signup, the user is automatically authenticated and can use the returned tokens
• The newUser field is always true for signup operations
• Only the password authentication method is supported for signup
• Store the refreshToken securely to refresh the access token when it expires
• Refresh the access token before it expires to prevent unnecessary API requests, as requests with an expired token will fail