Authentication

The ION Guard API uses Laravel Sanctum for authentication via Bearer tokens. Every authenticated access requires a valid token in the Authorization header.

Obtaining a token

Send the user credentials to the login endpoint:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "operador@empresa.com",
  "password": "sua-senha"
}

Success response (200)

{
  "token": "1|ionguard_abc123def456...",
  "user": {
    "id": "9c1a2b3c-...",
    "name": "João Silva",
    "email": "operador@empresa.com",
    "role": "operator",
    "status": "active",
    "password_login_enabled": true,
    "sso_login_enabled": false,
    "role_managed_by_sso": false,
    "tenant_id": "9c1a2b3c-...",
    "last_login_at": "2026-07-03T12:00:00-03:00",
    "created_at": "2026-01-10T09:30:00-03:00",
    "updated_at": "2026-07-03T12:00:00-03:00"
  }
}

Token prefix

Tokens are issued with the ionguard_ prefix (after the 1| identifier), which makes it easier for secret scanning tools to automatically detect leaked secrets.

Error responses

Status	Situation
401	Invalid credentials
403	Account is not active (inactive or blocked)
429	Too many attempts — rate limit exceeded

Using the token

Include the token in the Authorization header of every authenticated request:

GET /api/v1/sites
Authorization: Bearer 1|abc123def456...
Content-Type: application/json

Refreshing the token

To obtain a new token without logging in again, use the refresh endpoint. The current token is revoked and a new one is generated:

POST /api/v1/auth/refresh
Authorization: Bearer 1|abc123def456...

Response (200)

{
  "token": "2|xyz789ghi012..."
}

Previous token revoked

After the refresh, the previous token stops working. Use the new token in subsequent requests.

Token validity

Each token is valid for 24 hours (1440 minutes) from issuance. After that, the token expires and requests start returning 401 Unauthorized — you must obtain a new token via login or refresh.

The expiration time is defined on the server by the SANCTUM_TOKEN_EXPIRATION variable (in minutes); the installation administrator can adjust it.

Logout

To revoke the current token:

POST /api/v1/auth/logout
Authorization: Bearer 1|abc123def456...

Response (200)

{
  "message": "Logged out."
}

Rate limiting

The authentication endpoints have more restrictive rate limiting than the others:

Group	Limit
Auth (login, refresh, logout)	5 req/min
Authenticated endpoints	60 req/min

When the limit is exceeded, the API returns status 429 Too Many Requests with the Retry-After header indicating how many seconds to wait.

Permissions by profile

The token inherits the permissions of the user's profile. The same authorization rules from the web interface apply to the API:

Profile	Access
Platform Admin	All endpoints, all tenants
Tenant Master	All endpoints within their tenant
Tenant Admin	CRUD of sites, zones, devices, and operational users
Operator	Read + alert actions (acknowledge, resolve) on assigned sites
Viewer	Read-only on assigned sites

Full example (cURL)

# 1. Login
TOKEN=$(curl -s -X POST https://ionguard.exemplo.local/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"operador@empresa.com","password":"senha123"}' \
  | jq -r '.token')

# 2. List sites
curl -s https://ionguard.exemplo.local/api/v1/sites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

# 3. List a site's alerts
curl -s https://ionguard.exemplo.local/api/v1/sites/{site_id}/alerts \
  -H "Authorization: Bearer $TOKEN"

# 4. Acknowledge an alert
curl -s -X POST https://ionguard.exemplo.local/api/v1/alerts/{alert_id}/acknowledge \
  -H "Authorization: Bearer $TOKEN"

# 5. Logout
curl -s -X POST https://ionguard.exemplo.local/api/v1/auth/logout \
  -H "Authorization: Bearer $TOKEN"

Full reference

For the complete list of endpoints and their parameters, see the automatically generated interactive documentation:

https://<seu-servidor>/docs/api