Autenticação
Guias relacionados: Login local e 2FA, Password grant, Single Sign-On e Sessão e logout.
Os erros das rotas de autenticação vêm em JSON, com error e error_description.
POST /oauth/token
Emite o token de acesso por OAuth 2.0 password grant, somente com a autenticação nativa. Não aplica a 2FA e não aceita LDAP.
Acesso: público.
| Header | Valor |
|---|---|
Content-Type | application/x-www-form-urlencoded, exatamente assim |
| Campo (formulário) | Tipo | Obrigatório | Descrição |
|---|---|---|---|
grant_type | string | Sim | Sempre password. |
username | string | Sim | Operador. |
password | string | Sim | Senha do operador. |
Resposta 200
| Campo | Descrição |
|---|---|
access_token | Token de acesso para as chamadas seguintes. |
scope | Permissões do operador (JSON serializado em texto). |
operator | Operador autenticado. |
rest_name | Nome do cadastro da API. |
token_type | Bearer. |
Respostas
| HTTP | Significado |
|---|---|
200 | Token emitido. |
400 | Parâmetros ausentes (username, password), grant_type diferente de password ou corpo vazio. |
401 | Credenciais não aceitas ou operador bloqueado após exceder o limite de falhas das políticas de senha. |
415 | Content-Type diferente de application/x-www-form-urlencoded. |
500 | Erro interno. |
O token vale 60 minutos por padrão, ou o tempo definido em session_duration no config.json da API (máximo de 720 minutos).
POST /oauth/token HTTP/1.1
Host: api.exemplo.com:33070
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=<operador>&password=<senha>POST /oauth/v2/token
Primeira etapa do login, com a 2FA e o LDAP. Recebe o mesmo formulário de POST /oauth/token. Para LDAP, informe username no formato <provedor>/<operador>, com o nome do provedor LDAP cadastrado em ssoProviders.
Acesso: público.
| Situação | Resposta 200 |
|---|---|
| 2FA desabilitada | O token, no mesmo formato de POST /oauth/token. |
| 2FA habilitada, TOTP cadastrado | URL: caminho do desafio (/oauth/v2/token/mfa/{challengeID}). |
| 2FA habilitada, primeiro acesso | URL, secret (segredo TOTP em Base32) e qrcode (PNG de 200 × 200 em Base64 padrão). O segredo já fica gravado. |
As respostas de erro são as mesmas de POST /oauth/token.
POST /oauth/v2/token/mfa/{challengeID}
Segunda etapa do login com 2FA. Envie o código de 6 dígitos gerado pelo aplicativo autenticador.
Acesso: público.
| Header | Valor |
|---|---|
Content-Type | application/json, exatamente assim |
| Campo (JSON) | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Code | string | Sim | Código TOTP. |
Operator | string | Não | Ignorado: a API usa o operador do desafio. |
Respostas
| HTTP | Significado |
|---|---|
200 | Código válido. O corpo traz o token, no mesmo formato de POST /oauth/token. |
400 | Corpo vazio, JSON inválido ou Content-Type diferente de application/json. |
401 | Código inválido (Invalid code), desafio inexistente (You need to authenticate first at /oauth/token) ou operador bloqueado no quarto código errado. |
500 | Erro interno. |
POST /oauth/v2/token/mfa/<challengeID> HTTP/1.1
Host: api.exemplo.com:33070
Content-Type: application/json
{"Code": "123456"}Single Sign-On
Rotas disponíveis quando há provedores SSO no cadastro da API. São públicas e usadas pelo navegador.
| Método e rota | Chamada por | Descrição |
|---|---|---|
GET /auth/api/v1/sso/login?provider=<nome> | Navegador | Inicia o login. Responde 307 para o provedor (somente saml2 e oauth2), ou 400 em texto com provedor inválido. |
POST /auth/api/v1/sso/saml2/acs | Provedor SAML 2.0 | Recebe SAMLResponse e RelayState. |
GET /auth/api/v1/sso/oauth2 | Provedor OAuth 2.0 | Recebe code e state. |
POST /auth/api/v1/sso/saml2/slo | Provedor SAML 2.0 | Conclui o logout federado e redireciona (303) para o destino final. |
Os retornos de login redirecionam (303) para sso_login_redirect com token, token_type (Bearer) e scope (permissões em JSON codificado em Base64) na query string. Em caso de falha, com o parâmetro error.
DELETE /disconnect/api/v3/logout
Encerra a sessão e invalida o token.
Acesso: Bearer.
| Header | Valor |
|---|---|
Authorization | Bearer <access_token> |
Accept | application/json |
Resposta 200
| Campo | Tipo | Descrição |
|---|---|---|
data | string | Resultado da operação (Logout successful). |
redirect | string | Endereço de logout no provedor de identidade. Presente somente com sso_logout_end_session habilitado e sessão SSO. |
Respostas
| HTTP | Significado |
|---|---|
200 | Sessão encerrada. |
401 | Token ausente ou inválido. |
500 | Erro interno. |