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

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

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

Response

Success (200 OK):

{
  "user": {
    "email": "user@example.com"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": {
    "id": "role-id-here"
  }
}

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"
  }'

Authenticate with email and password.

Endpoint: POST /auth/login

Authentication: Not required

Request Body

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

Field	Type	Required	Description
email	string	Yes	User's email address
password	string	Yes	User's password

Response

Success (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

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.

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