Authentication — API v2

API v2 uses Bearer token authentication via Laravel Sanctum.

Create a Token

POST /auth/token is the path for programmatic clients. Besides email and password it requires the user's API key in the X-REST-API-KEY header:

curl -X POST "https://your-instance.example.com/api/v2/auth/token" \
  -H "Content-Type: application/json" \
  -H "X-REST-API-KEY: {user-api-key}" \
  -d '{
    "email": "user@example.com",
    "password": "YourPassword",
    "token_name": "api-client"
  }'

Response:

{
  "data": {
    "token": "1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "type": "bearer"
  },
  "meta": { "api_version": "2.0" }
}

The API key lives under Administration → Users → [User] → API key; new users receive one automatically. Without the header the endpoint answers 422, with a wrong key 401 Invalid API key.

Interactive login

For logging in from a UI there is POST /auth/login with {"email": …, "password": …} — no API key, but with password-expiry and lockout handling. /auth/token is meant for integrations.

In both cases the user needs the using_API operation, otherwise every API call answers with 403.

Long-lived API token (no password)

For permanent integrations the detour via /auth/token is unnecessary: an administrator issues a token under Administration → Users → [User] → API token, which is used directly as a bearer.

This is the preferred path for machine-to-machine access, because the client then stores just this one value — no password, no API key. The service user's password is also a UI login, so a leak of the client configuration would otherwise give away more than API access.

	API token	API key + login
Values to store	1 (token)	3 (key, email, password)
Password held by the client	no	yes
Individually revocable	yes	no (the key covers all)
Expiry date	optional	none
Renewal by the client	not possible	automatic on 401

A token carries the full permissions of its user — Sanctum abilities are not evaluated, the role is the permission boundary. The plain value is shown exactly once on issue (only a SHA-256 hash is stored); a new token does not invalidate existing ones, so a lost value can be replaced safely. Deleting a user immediately invalidates its tokens and its API key.

Use the Token

The token is sent as an Authorization header with all subsequent requests:

curl -X GET "https://your-instance.example.com/api/v2/inventories" \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Permissions

Permission	Description
inventory_view	View inventory
inventory_edit	Create/edit inventory, manage categories
inventory_delete	Delete inventory
calibration_view	View calibrations
calibration_edit	Create/edit calibrations
customers_view	View customers
customers_edit	Create/edit customers

Error Codes

HTTP Status	Meaning
401 Unauthorized	Missing or invalid credentials
403 Forbidden	Authentication successful, but insufficient permissions
404 Not Found	Requested endpoint or record does not exist
422 Unprocessable Entity	Validation error
500 Internal Server Error	Server error — check the application logs

Notes

• Always transmit credentials over HTTPS only
• Tokens can be revoked and recreated at any time
• For automated systems, a dedicated user account with a restricted role is recommended
• Permission checks follow the same rules as the web interface (RBAC)