Authentication¶

All access to the calServer REST API requires authentication. The API supports two authentication methods — depending on the API version.

API v2 — Bearer Token (Beta — calServer 6.0)¶

In Development

API v2 is under active development for calServer 6.0 and is not yet production-ready.

API v2 uses Bearer token authentication via Laravel Sanctum.

Generate Token¶

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

Response:

{
  "token": "1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

Use Token¶

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

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

Permissions (API v2)¶

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

API v1 — Header-Based Authentication¶

The legacy API v1 uses three HTTP headers for authentication.

Required Headers¶

Header	Description
`HTTP_X_REST_USERNAME`	Username of the API user
`HTTP_X_REST_PASSWORD`	Password of the API user
`HTTP_X_REST_API_KEY`	API key (generated in the user profile)

All three headers must be present in every request. If any header is missing or the values are invalid, the API will respond with an authentication error.

Example Request (API v1)¶

curl -X GET "https://your-instance.example.com/api/inventory" \
  -H "HTTP_X_REST_USERNAME: YourUsername" \
  -H "HTTP_X_REST_PASSWORD: YourPassword" \
  -H "HTTP_X_REST_API_KEY: YourAPIKey"

Create API Key¶

Log in to calServer
Open your user profile
Navigate to the API key section
Generate a new key

The API key is stored in the FrontendUserKey table and is associated with the respective user account.

Error Codes¶

HTTP Status	Meaning
`401 Unauthorized`	Missing or invalid credentials
`403 Forbidden`	Authentication successful, but missing permission
`404 Not Found`	Requested endpoint or record does not exist
`422 Unprocessable Entity`	Validation error (API v2 only)
`500 Internal Server Error`	Server error — check the application logs

Notes¶

Only transmit credentials over HTTPS
API keys and tokens can be revoked and regenerated 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)