Autenticação e sessão
Guias relacionados: Login local e MFA, Tokens OAuth, Sessão e logout e Primeiro acesso e senha.
GET POST /auth/login
Autentica o usuário com HTTP Basic e estabelece a sessão por cookie. Pode exigir MFA.
Acesso: HTTP Basic. Para provedor dedicado, o usuário segue o formato PROVEDOR\USUARIO.
| Header | Obrigatório | Valor |
|---|---|---|
Authorization | Sim | Basic <credenciais-base64> |
CF-Turnstile-Response | Condicional | Token do Cloudflare Turnstile. Obrigatório quando a validação está habilitada no ambiente. Veja Cloudflare Turnstile. |
Respostas
| HTTP | Significado | Corpo |
|---|---|---|
200 | Login concluído. A sessão é enviada em Set-Cookie: __Host-dirl_session. | LoginResponse |
206 | É necessária uma etapa de MFA. | MfaChallengeResponse |
400 | Credencial ausente ou header CF-Turnstile-Response ausente ou inválido. | — |
401 | Credencial não aceita. | — |
403 | Acesso negado ou token Turnstile rejeitado (inválido, expirado ou já utilizado). | — |
503 | Não foi possível validar o token Turnstile com a Cloudflare. | — |
POST /directlink/v2/auth/login HTTP/1.1
Host: api.exemplo.com
Authorization: Basic <credenciais-base64>
Accept: application/jsonGET POST /auth/mfa e /auth/mfa/register
/auth/mfa valida o segundo fator (status 1 e 2 do login). /auth/mfa/register confirma o cadastro do TOTP (status 3). Veja o fluxo em Concluir o MFA.
Acesso: link seguro recebido em linkURL na resposta 206 do login. Use a URL integral.
Envie o código no campo p: no formulário, com POST (recomendado), ou na query string, com GET.
| Campo | Obrigatório | Descrição |
|---|---|---|
p | Sim | /auth/mfa: PIN (e-mail ou SMS) ou código TOTP. /auth/mfa/register: código TOTP gerado pelo aplicativo com o segredo recebido. |
Respostas de /auth/mfa
| HTTP | Significado | Corpo |
|---|---|---|
200 | Segundo fator validado. A sessão é enviada em Set-Cookie: __Host-dirl_session. | LoginResponse |
400 | Link inválido ou expirado, ou p ausente. | — |
403 | Código TOTP inválido, usuário bloqueado ou não encontrado. | — |
Respostas de /auth/mfa/register
| HTTP | Significado | Corpo |
|---|---|---|
200 | TOTP cadastrado. Não estabelece sessão: faça o login de novo. | MfaRegisterResponse |
400 | Link inválido ou expirado, ou p ausente. | — |
403 | Código TOTP inválido ou falha ao gravar o segredo. | — |
POST <caminho-integral-do-link-seguro> HTTP/1.1
Host: api.exemplo.com
Content-Type: application/x-www-form-urlencoded
p=<pin-ou-codigo-totp>POST /auth/token e /oauth2/token
Emitem um token de acesso Bearer. Os dois caminhos são equivalentes.
Acesso: público; a credencial vai no formulário.
Corpo: application/x-www-form-urlencoded, conforme o grant.
| Campo | Password grant | Token exchange | Descrição |
|---|---|---|---|
grant_type | Sim: password | Sim: urn:ietf:params:oauth:grant-type:token-exchange | Tipo de grant. |
username | Sim | — | Usuário. |
password | Sim | — | Senha. |
subject_token_type | — | Sim: urn:ietf:params:oauth:token-type:jwt | Tipo do token de origem. Só JWT é aceito. |
subject_token | — | Sim | JWT de origem. |
provider | — | Não | Provedor que valida o JWT. Prevalece sobre o header X-STCPDIRECTLINK-JWT-ISSUER. |
| Header | Obrigatório | Descrição |
|---|---|---|
X-STCPDIRECTLINK-JWT-ISSUER | Não | Alternativa ao campo provider no token exchange. Não autentica as rotas protegidas. |
Respostas
| HTTP | Significado | Corpo |
|---|---|---|
200 | Token emitido. Inclui Cache-Control: no-store. | TokenResponse |
400 | Grant ou token de origem não aceito. | OAuthError |
POST /directlink/v2/oauth2/token HTTP/1.1
Host: api.exemplo.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=password&username=<usuario>&password=<senha>GET /auth/firstaccess
Inicia o primeiro acesso. Devolve o link seguro em linkURL e envia o PIN ao usuário por e-mail ou SMS.
Acesso: público.
| Parâmetro | Local | Obrigatório | Descrição |
|---|---|---|---|
u | query | Sim | Usuário. |
CF-Turnstile-Response | header | Condicional | Token do Cloudflare Turnstile, obrigatório quando a validação está habilitada. |
Respostas
| HTTP | Significado | Corpo |
|---|---|---|
200 | Link seguro em linkURL; PIN enviado ao usuário. | SecureLinkResponse |
400 | Header CF-Turnstile-Response ausente ou inválido. | — |
403 | Token Turnstile rejeitado (inválido, expirado ou já utilizado). | — |
503 | Não foi possível validar o token Turnstile com a Cloudflare. | — |
GET /auth/forget
Inicia a recuperação de senha. Devolve o link seguro em linkURL e envia o PIN ao usuário por e-mail ou SMS. Parâmetros e respostas iguais aos de /auth/firstaccess.
POST /auth/change
Conclui o primeiro acesso ou a recuperação de senha.
Acesso: link seguro (linkURL) devolvido por /auth/firstaccess ou /auth/forget. O k fica na URL e carrega os parâmetros de identificação e validade; não os construa manualmente.
Aceita somente POST. Envie p e z no corpo do formulário (application/x-www-form-urlencoded), nunca na URL:
| Campo (formulário) | Obrigatório | Descrição |
|---|---|---|
p | Sim | PIN ou código exigido pelo fluxo. |
z | Sim | Nova senha. |
Respostas
| HTTP | Significado | Corpo |
|---|---|---|
200 | Senha alterada. | OperationResponse |
400 | Dados ou link inválidos. | — |
403 | A troca de senha foi recusada. | — |
405 | Método diferente de POST. | — |
GET POST /auth/logout
Encerra a sessão local. Quando aplicável, limpa o cookie de sessão.
Acesso: sessão (token Bearer ou cookie).
Respostas
| HTTP | Significado |
|---|---|
200 | Sessão encerrada. |
401 | Credencial não aceita. |
POST /directlink/v2/auth/logout HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer <access_token>