Authentication API

This documentation is verified against the actual API test suite (test/auth.test.js).

Overview

Baasix provides three core authentication endpoints:

User registration
User login
Get current user information

Authentication Modes (authMode)

Baasix supports two authentication modes for token delivery. Pass the authMode parameter in login, register, or social sign-in requests:

Mode	Value	Description
JWT	`jwt` (default)	Token returned in response body
Cookie	`cookie`	Token set as HTTP-only cookie

JWT Mode (Default)

Token is returned in the response body. Store and include it in the Authorization header:

curl http://localhost:3000/items/posts \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Token is set as an HTTP-only cookie. Include credentials in requests:

fetch('http://localhost:3000/items/posts', {
  credentials: 'include',
});

For detailed authMode configuration and usage, see SSO & Social Authentication - Authentication Modes.

Register a New User

Create a new user account.

Endpoint: POST /auth/register

Authentication: Not required

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "user@example.com",
  "password": "password123",
  "authMode": "jwt"
}

Field	Type	Required	Description
firstName	string	Yes	User's first name
lastName	string	Yes	User's last name
email	string	Yes	User's email address
password	string	Yes	User's password
authMode	string	No	`jwt` (default) or `cookie`

Response

Success (200 OK):

{
  "message": "User registered successfully",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authMode": "jwt",
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "role": {
    "id": "role-id-here",
    "name": "user"
  },
  "permissions": [...],
  "tenant": null
}

Error (400 Bad Request):

When email already exists:

{
  "message": "User already exists"
}

Example

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "password": "securepass123",
    "authMode": "jwt"
  }'

Authenticate with email and password.

Endpoint: POST /auth/login

Authentication: Not required

Request Body

{
  "email": "user@example.com",
  "password": "password123",
  "authMode": "jwt"
}

Field	Type	Required	Description
email	string	Yes	User's email address
password	string	Yes	User's password
authMode	string	No	`jwt` (default) or `cookie`
tenant_Id	string	No	Tenant ID (for multi-tenant mode)

Response

Success (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authMode": "jwt",
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "role": {
    "id": "role-uuid",
    "name": "user"
  },
  "permissions": [...],
  "tenant": null
}

Error (400 Bad Request):

When password is incorrect:

{
  "message": "Incorrect password."
}

Example

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "securepass123"
  }'

Using the Token

Include the token in the Authorization header for subsequent requests:

curl http://localhost:3000/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Get Current User

Retrieve information about the authenticated user.

Endpoint: GET /auth/me

Authentication: Required (Bearer token)

Request Headers

Authorization: Bearer YOUR_TOKEN_HERE

Response

Success (200 OK):

{
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Error (401 Unauthorized):

When no authentication provided:

{
  "message": "Unauthorized"
}

Example

curl http://localhost:3000/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Refresh Token

Refresh the current access token to extend the session. This creates a new session and invalidates the old one.

Endpoint: POST /auth/refresh

Authentication: Required (Bearer token)

Request Headers

Authorization: Bearer YOUR_CURRENT_TOKEN
Content-Type: application/json

Request Body (Optional)

{
  "authMode": "jwt"
}

Field	Type	Description
`authMode`	string	Optional. `"jwt"` (default) or `"cookie"`

Response

Success (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authMode": "jwt",
  "expiresIn": 604800
}

Error (401 Unauthorized):

{
  "message": "Invalid or expired token"
}

Example

curl -X POST http://localhost:3000/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN" \
  -H "Content-Type: application/json"

User Logout

Log out the current user and invalidate their session.

Endpoint: GET /auth/logout

Authentication: Required (Bearer token)

Response

Success (200 OK):

{
  "message": "Logged out successfully"
}

Example

curl http://localhost:3000/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

Check Token

Verify if the current JWT token is valid.

Endpoint: GET /auth/check

Authentication: Required (Bearer token)

Response

Success (200 OK):

{
  "valid": true,
  "user": {
    "id": "user-uuid"
  }
}

Error (401 Unauthorized):

{
  "valid": false,
  "message": "Invalid or expired token"
}

Example

curl http://localhost:3000/auth/check \
  -H "Authorization: Bearer YOUR_TOKEN"

Request Magic Link

Request a magic link for passwordless authentication. An email with a login link or code will be sent to the user.

Endpoint: POST /auth/magiclink

Authentication: Not required

Request Body

{
  "email": "user@example.com",
  "link": "https://myapp.com",
  "mode": "link"
}

Field	Type	Required	Description
email	string	Yes	User's email address
link	string	Yes*	Base URL for the magic link (*required when mode is `"link"`)
mode	string	No	`"link"` (default) sends a clickable link, `"code"` sends a code

Note: When mode is "link", the email will contain a link like {link}/auth/magiclink/{token}. When mode is "code", the email will contain a short verification code.

Response

Success (200 OK):

{
  "message": "Instruction sent to your email"
}

Error (404 Not Found):

{
  "message": "User not found"
}

Error (400 Bad Request):

{
  "message": "Invalid link"
}

Example

curl -X POST http://localhost:3000/auth/magiclink \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "link": "https://myapp.com",
    "mode": "link"
  }'

Validate Magic Link

Validate a magic link token and authenticate the user.

Endpoint: GET /auth/magiclink/:token

Authentication: Not required

URL Parameters

Parameter	Type	Description
token	string	Magic link token from the email

Query Parameters

Parameter	Type	Description
authMode	string	Optional. `"jwt"` or `"cookie"`

Response

Success (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authMode": "jwt",
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "role": {
    "id": "role-uuid",
    "name": "user"
  }
}

Error (400 Bad Request):

{
  "message": "Invalid or expired magic link"
}

Example

curl "http://localhost:3000/auth/magiclink/abc123token?authMode=jwt"

Request Password Reset

Request a password reset email. A link with a reset token will be sent to the user's email.

Endpoint: POST /auth/password/reset

Authentication: Not required

Request Body

{
  "email": "user@example.com",
  "link": "https://myapp.com"
}

Field	Type	Required	Description
email	string	Yes	User's email address
link	string	Yes	Base URL for the reset link (email will contain `{link}/auth/reset-password/{token}`)

Response

Success (200 OK):

{
  "message": "If an account exists, a reset link will be sent"
}

Note: For security reasons, this endpoint always returns the same success message whether the email exists or not.

Example

curl -X POST http://localhost:3000/auth/password/reset \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "link": "https://myapp.com"
  }'

Reset Password with Token

Reset the user's password using a token received via email.

Endpoint: POST /auth/password/reset/:token

Authentication: Not required

URL Parameters

Parameter	Type	Description
token	string	Password reset token from email

Request Body

{
  "password": "newSecurePassword123"
}

Field	Type	Required	Description
password	string	Yes	The new password

Response

Success (200 OK):

{
  "message": "Password reset successfully"
}

Error (400 Bad Request):

{
  "message": "Invalid or expired reset token"
}

Example

curl -X POST http://localhost:3000/auth/password/reset/abc123token \
  -H "Content-Type: application/json" \
  -d '{
    "password": "newSecurePassword123"
  }'

Change Password

Change the current user's password. Requires the current password for verification.

Endpoint: POST /auth/password/change

Authentication: Required (Bearer token)

Request Body

{
  "currentPassword": "oldPassword123",
  "newPassword": "newSecurePassword456"
}

Field	Type	Required	Description
currentPassword	string	Yes	Current password
newPassword	string	Yes	New password to set

Response

Success (200 OK):

{
  "message": "Password changed successfully"
}

Error (400 Bad Request):

{
  "message": "Current password is incorrect"
}

Example

curl -X POST http://localhost:3000/auth/password/change \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "oldPassword123",
    "newPassword": "newSecurePassword456"
  }'

Request Email Verification

Request an email verification link to be sent to the user's email address.

Endpoint: POST /auth/email/verify

Authentication: Required (Bearer token)

Request Body

{
  "link": "https://myapp.com"
}

Field	Type	Required	Description
link	string	Yes	Base URL for the verification link (email will contain `{link}/auth/verify-email/{token}`)

Response

Success (200 OK):

{
  "message": "Verification email sent"
}

Already Verified (200 OK):

{
  "message": "Email already verified"
}

Example

curl -X POST http://localhost:3000/auth/email/verify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://myapp.com"
  }'

Verify Email with Token

Verify the user's email address using the token from the verification email.

Endpoint: GET /auth/email/verify/:token

Authentication: Not required

URL Parameters

Parameter	Type	Description
token	string	Email verification token

Response

Success (200 OK):

{
  "message": "Email verified successfully"
}

Error (400 Bad Request):

{
  "message": "Invalid or expired verification token"
}

Example

curl "http://localhost:3000/auth/email/verify/abc123token"

Authentication Flow

Typical authentication flow:

Register - Create a new user account
```
POST /auth/register → Returns token
```
Login - Authenticate existing user
```
POST /auth/login → Returns token
```

Access Protected Resources - Use token in requests

GET /auth/me
GET /items/:collection
... (with Authorization header)

Permissions

The /auth/me endpoint requires the user to have read permissions for the baasix_User collection. Administrators can grant this permission using the permissions API:

curl -X POST http://localhost:3000/permissions \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_Id": "user-role-id",
    "collection": "baasix_User",
    "action": "read",
    "fields": "*"
  }'

Default Admin Account

The system creates a default admin account during initialization:

Email: admin@baasix.com
Password: admin@123

Security Warning: Change the default admin password immediately in production environments.

SSO & Social Authentication - Google, GitHub, Facebook, and Apple Sign In

Core API Routes

Item Routes - CRUD operations for collections
Schema Routes - Dynamic schema management
API Routes Reference - Complete endpoint listing

Access Control

Permission Routes - Role-based access control
Session Limits Feature - Control concurrent sessions per user

Multi-tenant

Multi-tenant Guide - Tenant-based authentication and isolation

Real-time

Socket.IO Integration - Authenticate WebSocket connections

Guides

Integration Guide - Client-side authentication implementation
Error Handling Guide - Handle authentication errors
Deployment Guide - JWT and CORS configuration

On this page