MantisBase provides standalone authentication endpoints for user login, token refresh, and logout. These endpoints are separate from entity endpoints and handle JWT token management.

🌐 Base URL

http://localhost:7070/api/v1/auth/

📄 Authentication Endpoints

Method	Endpoint	Description
POST	`/api/v1/auth/login`	Authenticate user and get token
POST	`/api/v1/auth/refresh`	Refresh an existing token
POST	`/api/v1/auth/logout`	Logout (invalidate token)
POST	`/api/v1/auth/setup/admin`	Create initial admin account

🔑 Login

Authenticate a user and receive a JWT token.

‍⚠️ Rate Limiting: This endpoint is rate-limited to 5 attempts per minute per IP address to prevent brute force attacks. If you exceed this limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can try again.

Endpoint: POST /api/v1/auth/login

Request Body:

{
  "entity": "users",
  "identity": "user@example.com",
  "password": "userpassword"
}

Request Fields:

entity (required): The entity/table name where the user account exists (e.g., "users", "mb_admins")
identity (required): User identifier - can be either an email address or user ID
password (required): User's password

Response (Success - 200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "123456",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Response (Error - 404):

{
  "status": 404,
  "data": {},
  "error": "No user found for given `identity`, `password` & `entity` combination."
}

Response (Rate Limited - 429):

{
  "status": 429,
  "data": {},
  "error": "Rate limit exceeded. Maximum 5 requests per 60 seconds. Retry after 45 seconds."
}

The rate limit response includes these headers:

X-RateLimit-Limit: Maximum requests allowed (5)
X-RateLimit-Remaining: Remaining requests in window (0 when rate limited)
X-RateLimit-Reset: Unix timestamp when the window resets
Retry-After: Seconds to wait before retrying

Examples:

Login with email:

curl -X POST http://localhost:7070/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "users",
    "identity": "user@example.com",
    "password": "userpassword"
  }'

Login with user ID:

curl -X POST http://localhost:7070/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "users",
    "identity": "019b292a-e145-7000-813b-c9f528364a2b",
    "password": "userpassword"
  }'

🔄 Refresh Token

Refresh an existing JWT token to extend its validity.

Endpoint: POST /api/v1/auth/refresh

Request Headers:

Authorization: Bearer <existing_token>

Response (Success - 200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "123456",
    "email": "user@example.com"
  }
}

Example:

curl -X POST http://localhost:7070/api/v1/auth/refresh \

-H "Authorization: Bearer <existing_token>"

🚪 Logout

Logout and invalidate the current token.

Endpoint: POST /api/v1/auth/logout

Request Headers:

Authorization: Bearer <token>

Response (Success - 200):

{
  "message": "Logged out successfully"
}

Example:

curl -X POST http://localhost:7070/api/v1/auth/logout \

-H "Authorization: Bearer <token>"

👤 Setup Admin

Create the initial admin account. This endpoint is typically used during first-time setup when no admin accounts exist. This is called by the system, do not use it.

Endpoint: POST /api/v1/auth/setup/admin

Request Body:

{
  "email": "admin@example.com",
  "password": "adminpassword"
}

Response (Success - 200):

{
    "id": "admin123",
    "email": "admin@example.com",
    "entity": "mb_admins"
}

Example:

curl -X POST http://localhost:7070/api/v1/auth/setup/admin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "adminpassword"
  }'

‍⚠️ Note: This endpoint is only available when no admin accounts exist. Once an admin is created, use the regular login endpoint or create additional admins via the CLI: mantisbase admins --add <email>

</blockquote>

🔐 Using Tokens

After receiving a token from the login endpoint, include it in all subsequent API requests:

Authorization: Bearer <token>

The token contains user information (id, entity) and is validated automatically by the getAuthToken() middleware on all endpoints.

⏱️ Token Expiration

By default, tokens expire after 1 hour. Use the refresh endpoint to extend token validity without requiring the user to log in again.

🏁 Summary

The authentication API provides secure user authentication with JWT tokens. Tokens are automatically validated on all entity endpoints, ensuring only authenticated users can access protected resources.