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

Overview

The login endpoint authenticates users with their email/username and password, returning an access token and refresh token for subsequent API requests.
The endpoint accepts either email or username along with password. At least one identifier (email or username) must be provided.

Request

Body Parameters

email
string
User’s email address. Either email or username must be provided.
username
string
User’s username. Either email or username must be provided.
password
string
required
User’s password. Must be at least 6 characters long.Validation:
  • Minimum length: 6 characters
  • Required field

Response

accessToken
string
JWT access token for authenticating API requests. This token should be included in the Authorization header as a Bearer token for protected endpoints.Expiration: 24 hours from issuance
refreshToken
string
JWT refresh token used to obtain a new access token when the current one expires. Store this securely on the client side.
user
object
User information object containing profile details and permissions.

Code Examples

interface LoginCredentials {
  email?: string;
  username?: string;
  password: string;
}

interface LoginResponse {
  accessToken: string;
  refreshToken: string;
  user: {
    id: number;
    email: string;
    username: string;
    firstName: string;
    lastName: string;
    rol: string;
    avatar: string;
    status: string;
    lastLogin: string;
    createdAt: string;
    permissions: string[];
    stats: Record<string, any>;
  };
}

async function login(credentials: LoginCredentials): Promise<LoginResponse> {
  const response = await fetch('https://api.example.com/api/v1/auths/sign-in', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(credentials),
  });
  
  if (!response.ok) {
    throw new Error('Login 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 with email
const result = await login({
  email: '[email protected]',
  password: 'password123'
});

// Usage with username
const result = await login({
  username: 'johndoe',
  password: 'password123'
});

Error Responses

401
error
Unauthorized - Invalid credentials
{
  "statusCode": 401,
  "message": "Invalid email or password"
}
403
error
Forbidden - Account is not active
{
  "statusCode": 403,
  "message": "Account is inactive. Contact administrator."
}
400
error
Bad Request - Invalid request format or missing required fields
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "password must be at least 6 characters"
  ]
}

Implementation Notes

Security Best Practices:
  • Always use HTTPS in production
  • Store tokens securely (use httpOnly cookies or secure storage)
  • Never log or expose tokens in client-side code
  • Implement token refresh logic before access token expires

Token Storage

The access token should be included in the Authorization header for all authenticated requests:
Authorization: Bearer <accessToken>

Token Lifecycle

  1. Login: Receive accessToken and refreshToken
  2. Use: Include accessToken in API requests
  3. Refresh: When accessToken expires, use refreshToken to get a new one
  4. Logout: Clear tokens from storage
The backend maps the rol field to role on the frontend. Make sure to handle this mapping in your client code.

Build docs developers (and LLMs) love