Referência completa da API

Renova o access_token usando o refresh_token. O refresh_token antigo é revogado e um novo é emitido (Token Rotation).

Request Body

{ "refresh_token": "eyJ..." }

Resposta 200

{ "access_token": "eyJ...", "refresh_token": "eyJ...", "token_type": "bearer", "expires_in": 1800 }

401 — token inválido ou expirado

Revoga o refresh_token informado, inserindo-o na blacklist.

Request Body

{ "refresh_token": "eyJ..." }

Resposta: 200 {"message": "Logout realizado com sucesso"}

Retorna dados do usuário autenticado no token.

{ "id":1, "username":"admin", "role":"admin", "full_name":"Admin", "email":"admin@empresa.com", "last_login":"2025-03-01T10:00:00" }

Cria um novo usuário. A role deve ser menor ou igual à role do criador.

{
  "username":  "joao.silva",     // 3–50 chars, regex [a-zA-Z0-9_\-.]+
  "password":  "Senha@2025",      // mínimo 8 caracteres
  "full_name": "João Silva",
  "email":     "joao@empresa.com",
  "role":      "operator"          // readonly | operator | admin | superadmin
}

Resposta: 201 com objeto do usuário criado (sem hashed_password).

Lista todos os usuários. Resposta: array de objetos User.

curl -H "Authorization: Bearer $TOKEN" https://<host>/api/v1/users/

Retorna perfil do usuário autenticado. Qualquer role pode acessar.

Altera full_name e email do próprio usuário. Não pode alterar role.

{ "full_name": "João da Silva", "email": "novo@empresa.com" }

Altera a própria senha. Exige confirmação da senha atual.

{ "current_password": "SenhaAtual123", "new_password": "NovaSenha456" }

400 se senha atual incorreta · 400 se senha nova < 8 chars

Atualiza full_name, email, role, disabled de qualquer usuário. Invalida o cache do usuário modificado.

{ "role": "readonly", "disabled": true }

Desabilita (soft delete) o usuário. Não é possível deletar o próprio usuário autenticado.

400 — tentativa de deletar a si mesmo

Cadastra um novo controlador UniFi. A senha é criptografada com Fernet AES-128 antes de ser armazenada.

{
  "name":       "Filial SP",
  "host":       "192.168.1.100",
  "port":       8443,
  "username":   "admin",
  "password":   "senhaUnifi",
  "site":       "default",
  "verify_ssl": false,
  "enabled":    true
}

Resposta: 201 com objeto do controlador (sem senha em texto claro).

Query Params

Retorna detalhes de um controlador pelo ID. Senha nunca é retornada.

Atualiza os dados do controlador. Dispara reload do ControllersManager.

{ "name": "Filial SP — Atualizado", "enabled": false }

Remove o controlador do banco e do ControllersManager.

Reinicia a sessão do controlador específico no ControllersManager, reabrindo a conexão aiohttp.

Retorna status de saúde em tempo real de todos os controladores cadastrados.

[{
  "id": 1, "name": "Filial SP", "host": "192.168.1.100",
  "online": true, "response_time_ms": 42,
  "circuit_breaker": "closed"
}]

Total de controladores, percentual online, tempo médio de resposta, totais de clientes e dispositivos.

Dispositivos de todos os controladores em uma única lista agregada.

Clientes (connectados) de todos os controladores agregados.

Lista dispositivos de um controlador específico pelo ID.

Clientes básicos de um controlador específico.

Query Params

{
  "items": [{ "mac":"aa:bb:cc:dd:ee:ff", "name":"AP-Recepção", "type":"uap", "state":"online", "model":"U6-Lite" }],
  "total": 12, "page": 1, "page_size": 50,
  "summary": { "online": 10, "offline": 2 }
}

Retorna detalhes completos de um dispositivo pelo MAC.

Envia comando de reboot para o dispositivo via API UniFi (cmd/devmgr).

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  "https://<host>/api/v1/device/1/aa:bb:cc:dd:ee:ff/reboot"

Query Params

Retorna hostname, IP, MAC normalizado, SSID, banda, RSSI, signal% para wireless. Porta de switch para wired.

Contagens: total, wireless, wired, guest, blocked.

Detalhes completos de um cliente pelo MAC.

Bloqueia o cliente no controlador UniFi via cmd/stamgr.

Desbloqueia um cliente previamente bloqueado.

Lista SSIDs com contagem de clientes, VLAN herdada de networkconf. Suporta filtro enabled_only.

Consulta em paralelo: wlanconf + networkconf + sta.

Redes configuradas: VLAN ID, subnet CIDR, DHCP habilitado, dot1x enabled.

Tabela de rotas do controlador.

Resumo da rede: total de redes, VLANs, WLANs habilitadas.

Alertas de segurança enriquecidos com nome do AP (mac → name). Paginação via page / page_size.

Arquiva todos os alertas ativos via cmd/evtmgr no controlador.

Arquiva múltiplos alertas em paralelo (asyncio.gather).

{ "alert_ids": ["id1", "id2", "id3"] }

Retorna detalhes de um alerta específico pelo ID.

Versão de firmware de todos os dispositivos. Flag upgradable: true caso haja atualização disponível.

Resumo: total de alertas ativos, dispositivos com firmware desatualizado.

Query Params

Todos os eventos sem filtro de janela de tempo. Suporta paginação.

Alertas ativos do log (não arquivados).

Contagem de eventos por categoria e nível de severidade.

Histórico de throughput em Mbps para o controlador. Use controller_id=0 para agregado de todos.

Query Params

{
  "controller_id": 1,
  "source": "influxdb",
  "data": [
    { "time": "2025-03-01T10:00:00Z", "tx_mbps": 45.2, "rx_mbps": 22.8 },
    { "time": "2025-03-01T10:00:30Z", "tx_mbps": 50.1, "rx_mbps": 25.3 }
  ]
}

Query Params

curl -H "Authorization: Bearer $TOKEN" \
  "https://<host>/api/v1/audit/logs?action=login&status=failure&hours=24"

Resumo: total de eventos, eventos por ação, eventos por usuário, taxa de falhas.

Retorna configuração do bot. O token é mascarado (tok6…n4).

Envia uma mensagem de teste para o chat configurado. 400 se bot_token ou chat_id inválidos.

Solicita reset via e-mail. Sempre retorna 200 mesmo se o e-mail não existir (anti-enumeração).

{ "email": "usuario@empresa.com" }

Resposta: {"message": "Se o e-mail existir, você receberá as instruções."}

Confirma o reset com token recebido por e-mail e define nova senha.

{
  "token":        "abc123token",
  "new_password": "NovaSenha@2025"
}

Requisitos: ≥8 chars, ≥1 maiúscula, ≥1 minúscula, ≥1 dígito.

400 — token inválido/expirado ou senha fora dos requisitos.

Retorna pares chave-valor do arquivo .env. Campos sensíveis são mascarados com ••••.

Atualiza variáveis no .env preservando comentários e linhas em branco. Reinicia o serviço via systemctl restart unifi-api.

{ "SMTP_HOST": "smtp.empresa.com", "SMTP_PORT": "587" }

Envia e-mail de teste com as configurações SMTP atuais.

Stream de status de todos os controladores, atualizado a cada 10 segundos.

Protocolo de conexão

const ws = new WebSocket("wss://<host>/ws/status");
ws.onopen = () => {
  // 1. Autenticar enviando o token como 1ª mensagem
  ws.send(JSON.stringify({ token: "eyJ..." }));
};
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data); // Array de status dos controladores
};

Payload recebido (a cada 10s)

[{
  "id": 1, "name": "Filial SP", "online": true,
  "wlan_clients": 42, "wired_clients": 5,
  "alarms": 0, "response_time_ms": 38
}]

Stream detalhado de um único controlador. Inclui contagens de dispositivos, clientes e alarmes.

Verifica a saúde da aplicação. Ideal para probe de liveness no systemd/Kubernetes.

{ "status": "healthy", "version": "1.0.0", "uptime_seconds": 3600 }

Versão da API, ambiente, total de controladores registrados.

Mensagem de boas-vindas com links para /health e /docs.