Skip to main content
POST
/
api
/
v1
/
auths
/
sign-up
Register
curl --request POST \
  --url https://api.example.com/api/v1/auths/sign-up \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "username": "<string>",
  "phone": "<string>"
}
'
{
  "400": {},
  "409": {},
  "500": {},
  "accessToken": "<string>",
  "refreshToken": "<string>",
  "user": {
    "id": 123,
    "username": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "role": "<string>",
    "avatar": "<string>",
    "status": "<string>",
    "lastLogin": "<string>",
    "createdAt": "<string>",
    "permissions": [
      {}
    ],
    "stats": {}
  }
}

​
Overview

The registration endpoint creates a new user account in the system. Upon successful registration, it returns access tokens and user information, automatically logging in the new user.
New users are automatically assigned the “autor” role and can start creating content immediately.

​
Request

​
Body Parameters

​
email
string
required
User’s email address. Must be unique and valid.Validation:
  • Must be a valid email format
  • Must not already exist in the system
  • Required field
​
password
string
required
User’s password for authentication.Validation:
  • Minimum length: 6 characters
  • Required field
Passwords should be strong and include a mix of letters, numbers, and special characters.
​
first_name
string
required
User’s first name.Validation:
  • Required field
  • Used to generate default username and avatar
​
last_name
string
required
User’s last name.Validation:
  • Required field
  • Used to generate default username and avatar
​
username
string
Custom username for the account. If not provided, will be auto-generated from first and last name.Auto-generation format: firstname_lastname (lowercase)Example: John Doe → john_doe
​
phone
string
User’s phone number (optional).

​
Response

​
accessToken
string
JWT access token for authenticating API requests. Use this token immediately after registration.Expiration: 24 hours from issuance
​
refreshToken
string
JWT refresh token for obtaining new access tokens.
​
user
object
Newly created user object with profile information.

​
Code Examples

interface RegisterData {
  email: string;
  password: string;
  first_name: string;
  last_name: string;
  username?: string;
  phone?: string;
}

interface RegisterResponse {
  accessToken: string;
  refreshToken: string;
  user: {
    id: number;
    email: string;
    username: string;
    firstName: string;
    lastName: string;
    role: string;
    avatar: string;
    status: string;
    lastLogin: string;
    createdAt: string;
    permissions: string[];
    stats: {
      postsCreated: number;
      postsPublished: number;
      totalViews: number;
    };
  };
}

async function register(userData: RegisterData): Promise<RegisterResponse> {
  const response = await fetch('https://api.example.com/api/v1/auths/sign-up', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(userData),
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Registration failed');
  }
  
  const data = await response.json();
  
  // Store tokens securely
  localStorage.setItem('access_token', data.accessToken);
  localStorage.setItem('refresh_token', data.refreshToken);
  localStorage.setItem('user_data', JSON.stringify(data.user));
  
  return data;
}

// Usage
const newUser = await register({
  email: '[email protected]',
  password: 'SecurePass123!',
  first_name: 'John',
  last_name: 'Doe',
  phone: '+1234567890'
});

console.log('Registered and logged in as:', newUser.user.email);

​
Error Responses

​
409
error
Conflict - Email already exists
{
  "statusCode": 409,
  "message": "Email already registered"
}
​
400
error
Bad Request - Validation errors
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "email must be a valid email",
    "password must be at least 6 characters",
    "first_name is required"
  ]
}
​
500
error
Internal Server Error - Server error during registration
{
  "statusCode": 500,
  "message": "Failed to create user account"
}

​
Email Validation

Before submitting the registration form, you can check if an email is already registered using the email validation endpoint: 
async function checkEmailAvailability(email: string): Promise<boolean> {
  const response = await fetch('https://api.example.com/api/v1/auths/validate-email', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email }),
  });
  
  const data = await response.json();
  return !data.exists; // Returns true if email is available
}

// Usage
const isAvailable = await checkEmailAvailability('[email protected]');
if (!isAvailable) {
  console.log('Email already registered');
}

​
Default User Configuration

​
Auto-Generated Fields

If not provided, the following fields are automatically generated:
  • Username: Generated from first_name and last_name in the format firstname_lastname (lowercase)
  • Avatar: Generated using UI Avatars service with user’s initials and a blue background
  • Role: Defaults to "autor" (Author)
  • Status: Defaults to "active"
  • Permissions: Defaults to author permissions (comentar, crear_post, editar_post_propio, reaccionar)

​
Initial Statistics

All new users start with zero statistics:
  • Posts Created: 0
  • Posts Published: 0
  • Total Views: 0

​
Post-Registration Flow

  1. Automatic Login: User is automatically logged in after registration
  2. Token Storage: Store both access and refresh tokens securely
  3. Redirect: Redirect user to dashboard or onboarding flow
  4. Profile Setup: Allow user to update their profile and avatar
Remember to implement proper token storage and security measures. Never expose tokens in logs or client-side code.

Build docs developers (and LLMs) love

Get started for freeTalk to us