Authentication

You'll need to authenticate your requests to access any of the endpoints in the Mainframe API. In this guide, we'll look at how authentication works using Laravel Sanctum's session-based CSRF flow.

Session-based Authentication

The Mainframe API uses Laravel Sanctum for SPA (Single Page Application) authentication, backed by Laravel Fortify for the login endpoint. This uses session cookies and CSRF tokens rather than API tokens.

Step 1: Get CSRF Cookie

First, make a request to get the CSRF token cookie:

Get CSRF cookie

curl -X GET https://your-domain.com/sanctum/csrf-cookie \
  -H "Accept: application/json" \
  --cookie-jar cookies.txt

Step 2: Login

Use the CSRF token to authenticate against the login endpoint, which lives at the application root (not under /api):

Login request

curl -X POST https://your-domain.com/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie cookies.txt \
  --cookie-jar cookies.txt \
  -d '{
    "username": "admin",
    "password": "password"
  }'

If the account has two-factor authentication enabled, the login response returns { "two_factor": true } instead of completing the session. Follow up with a request to /two-factor-challenge with { "code": "123456" } to finish authenticating.

Step 3: Make authenticated requests

After login, include the session cookie in all subsequent requests. Read requests only need the cookie; write requests (POST, PUT, PATCH, DELETE) also need the X-XSRF-TOKEN header:

Authenticated request

curl https://your-domain.com/api/profile \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie cookies.txt

The session cookie is named mainframe_session by default (derived from the app name). It is automatically managed when using a browser-based SPA client. For server-to-server integrations, you need to manage cookies and CSRF tokens manually.

Authentication Flow

The complete authentication flow works as follows:

GET /sanctum/csrf-cookie — Retrieve the XSRF token cookie.
POST /login — Authenticate with username and password.
POST /two-factor-challenge — Only if the account has 2FA enabled.
GET /api/profile — Fetch the authenticated user profile.
All subsequent /api/* requests include the session cookie automatically.

Roles

Users are assigned roles, and API routes for each module are gated by role middleware. For example, the Payroll routes require Super Admin or Payroll Admin, and the Personnel Management routes require Super Admin, HR Admin, or HR Timekeeping:

Name
Super Admin
Type
role
Description
Full access across modules, including Control Center administration.
Name
Payroll Admin
Type
role
Description
Access to the Payroll module's endpoints (rosters, payroll items, processing).
Name
HR Admin
Type
role
Description
Access to Personnel Management administrative endpoints (employees, settings, approval paths).
Name
HR Timekeeping
Type
role
Description
Access to Personnel Management timekeeping endpoints (DTR, leave requests, pass slips).
Name
User Manager
Type
role
Description
Access to Control Center user management endpoints.

This is not an exhaustive list of every role in the system — only the ones directly relevant to the modules and endpoints documented here.

Disabled accounts

If a user account has been disabled, every /api/* request for that account returns a 403 response, regardless of role. See Errors for the exact response shape.

Logout

To end a session, send a POST request to the logout endpoint:

Logout

curl -X POST https://your-domain.com/logout \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie cookies.txt