Authentication API

MantisBase provides authentication endpoints scoped to auth-type entities. Each auth entity exposes login, refresh, and logout under /api/v1/auth/<entity>/.

Admin authentication uses /api/v1/sys/admins/ instead.

---

🌐 Base URL

http://localhost:7070/api/v1/auth/<entity>/

<entity> must be a registered entity that is:

• Type auth
• Not a system entity (e.g. not mb_admins)
• API-enabled (has_api: true)

If the entity is missing or does not meet these requirements, the route returns 404 Route Not Found.

---

📄 Authentication Endpoints

Method	Endpoint	Description
POST	/api/v1/auth/<entity>/login	Authenticate user and get token
POST	/api/v1/auth/<entity>/refresh	Refresh an existing token
POST	/api/v1/auth/<entity>/logout	Logout (invalidate token)

For admin authentication and initial setup, see System Endpoints – Admin Accounts (/api/v1/sys/admins/).

---

🔑 Login

Authenticate a user and receive a JWT token.

‍⚠️ Rate Limiting: Login 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/<entity>/login

Request Body:

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

Request Fields:

• identity (required): User identifier — email address or user ID
• password (required): User's password

The target entity is taken from the URL path, not the request body.

Response (Success - 200):

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

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/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "user@example.com",
    "password": "userpassword"
  }'

Login with user ID:

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

---

🔄 Refresh Token

Refresh an existing JWT token to extend its validity.

Endpoint: POST /api/v1/auth/<entity>/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/users/refresh \
  -H "Authorization: Bearer <existing_token>"

---

🚪 Logout

Logout and invalidate the current token.

Endpoint: POST /api/v1/auth/<entity>/logout

Request Headers:

Authorization: Bearer <token>

Response (Success - 200):

{
  "message": "Logged out successfully"
}

Example:

curl -X POST http://localhost:7070/api/v1/auth/users/logout \
  -H "Authorization: Bearer <token>"

---

👤 Admin Setup and Authentication

Admin account setup and admin-only authentication use the /api/v1/sys/admins/ namespace. See System Endpoints – Admin Accounts in the API reference.

Initial setup: POST /api/v1/sys/admins/setup (only when no admin accounts exist)

Admin login: POST /api/v1/sys/admins/login

---

🔐 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 scoped to auth-type entities. Tokens are automatically validated on all entity endpoints, ensuring only authenticated users can access protected resources.