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..."

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