Autenticação

A API do ION Guard utiliza Laravel Sanctum para autenticação via tokens Bearer. Todo acesso autenticado requer um token válido no header Authorization.

Obtendo um token

Envie as credenciais do usuário para o endpoint de login:

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

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

Resposta de sucesso (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"
  }
}

Prefixo do token

Os tokens são emitidos com o prefixo ionguard_ (após o identificador 1|), o que facilita a detecção automática de segredos vazados por ferramentas de secret scanning.

Respostas de erro

Status	Situação
401	Credenciais inválidas
403	Conta não está ativa (inativa ou bloqueada)
429	Muitas tentativas — rate limit excedido

Usando o token

Inclua o token no header Authorization de todas as requisições autenticadas:

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

Renovando o token

Para obter um novo token sem refazer login, use o endpoint de refresh. O token atual é revogado e um novo é gerado:

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

Resposta (200)

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

Token anterior revogado

Após o refresh, o token anterior deixa de funcionar. Use o novo token nas requisições seguintes.

Validade do token

Cada token tem validade de 24 horas (1440 minutos) a partir da emissão. Depois disso, o token expira e as requisições passam a retornar 401 Unauthorized — é necessário obter um novo token via login ou refresh.

O tempo de expiração é definido no servidor pela variável SANCTUM_TOKEN_EXPIRATION (em minutos); o administrador da instalação pode ajustá-lo.

Logout

Para revogar o token atual:

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

Resposta (200)

{
  "message": "Logged out."
}

Rate limiting

Os endpoints de autenticação possuem rate limiting mais restritivo que os demais:

Grupo	Limite
Auth (login, refresh, logout)	5 req/min
Endpoints autenticados	60 req/min

Quando o limite é excedido, a API retorna status 429 Too Many Requests com o header Retry-After indicando quantos segundos aguardar.

Permissões por perfil

O token herda as permissões do perfil do usuário. As mesmas regras de autorização da interface web se aplicam à API:

Perfil	Acesso
Platform Admin	Todos os endpoints, todos os tenants
Tenant Master	Todos os endpoints dentro do seu tenant
Tenant Admin	CRUD de sites, zonas, dispositivos e usuários operacionais
Operator	Leitura + ações de alerta (acknowledge, resolve) nos sites atribuídos
Viewer	Somente leitura nos sites atribuídos

Exemplo completo (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. Listar sites
curl -s https://ionguard.exemplo.local/api/v1/sites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

# 3. Listar alertas de um site
curl -s https://ionguard.exemplo.local/api/v1/sites/{site_id}/alerts \
  -H "Authorization: Bearer $TOKEN"

# 4. Reconhecer um alerta
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"

Referência completa

Para a lista completa de endpoints e seus parâmetros, consulte a documentação interativa gerada automaticamente:

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