A DL Pay Acquirer possui dois mecanismos paralelos de autenticação que compartilham o mesmo cabeçalho Authorization: Bearer <token>. O servidor inspeciona o token e o resolve para um usuário ou para um seller, dependendo do que o token de fato representa. Esta página explica como cada caminho funciona, quando usar cada um, como o ciclo de vida do JWT se comporta (incluindo rotação de refresh), como as chaves de API são emitidas, como a tabela de acessos concede a usuários acesso a sellers, e quais endpoints podem ser chamados sem nenhuma credencial.
Para o uso cotidiano de “como faço login”, consulte a página mais curta de Autenticação. Este guia é o aprofundamento — leia-o ao projetar uma integração ou modelar permissões.

​
Os dois mecanismos

MecanismoEmitido paraFormato do tokenIdentificaChamador típico
JWT (usuário)Um usuário da plataformaDois JWTs curtos (access, refresh)Um usuário realPainel, ferramentas internas, qualquer backend agindo como uma pessoa
Chave de API (seller)Um sellerUma string UUID criada no painelUma conta de sellerBackend do próprio seller, agindo em seu próprio nome
Ambos os mecanismos enviam seu token da mesma forma: 
Authorization: Bearer <access_token_or_api_key>
O servidor escolhe automaticamente o caminho de resolução correto — não é necessário enviar um cabeçalho diferente nem chamar um host diferente.

​
Qual devo usar?

Use JWT quando um humano está fazendo login (painel, aplicativo mobile, ferramentas de suporte). O token representa quem está fazendo a chamada, e a tabela de acessos define sobre quais sellers esse usuário pode atuar.Use uma chave de API quando o próprio backend do seller chama a plataforma em seu próprio nome — por exemplo, gerando links de checkout para os clientes do seller, ou sincronizando transações para o ERP do seller. A chave carrega a identidade do seller diretamente.

​
Como os tokens são resolvidos

A autenticação em cada endpoint protegido passa pelo módulo de autenticação da plataforma. Existem duas classes de autenticação:
  • Classe de autenticação somente de usuário — aceita apenas JWT.
  • Classe de autenticação combinada — aceita JWT ou uma chave de API de seller.
Ambas verificam o cabeçalho Authorization: Bearer … e, então, tentam, nesta ordem: um token JWT de acesso válido e — para a classe combinada — uma busca por chave de API com active=True.

​
O que o contexto autenticado representa

Tipo de tokenIdentidade resolvidaCredencial bruta
JWT válidoA instância de usuário correspondente (autenticado)O JWT decodificado
Chave de API válidaUm marcador de usuário transitório (sem registro persistido, tratado como autenticado para a requisição)A string bruta da chave de API
Sem token ou token inválidoUsuário anônimoNenhuma
Quando autenticado por uma chave de API, a identidade resolvida não é um usuário real — é uma instância transitória. Verificações de permissão recairão sobre a checagem por seller na tabela de acessos, e não sobre o sistema padrão de permissões da plataforma. Endpoints que precisam distinguir “pessoa fazendo a chamada” de “seller sendo manipulado” devem usar a classe de autenticação somente de usuário (apenas JWT) em vez da combinada.

​
Ciclo de vida do JWT

A configuração de JWT da plataforma controla a duração dos tokens:
ParâmetroValor
ACCESS_TOKEN_LIFETIME1 dia
REFRESH_TOKEN_LIFETIME4 dias
ROTATE_REFRESH_TOKENSTrue

​
Login

POST /user/login/ retorna: 
{
  "access": "eyJ0eXAiOiJKV1Qi...",
  "refresh": "eyJ0eXAiOiJKV1Qi...",
  "access_token_renew_interval": "86400",
  "user": { "id": 42, "email": "owner@example.com", "..." }
}
access_token_renew_interval é o TTL do token de acesso em segundos. Renove antes que ele expire. 
curl -X POST "https://api.dlpay.cloud/user/login/" \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@example.com", "password": "..."}'

​
Refresh com rotação

Como ROTATE_REFRESH_TOKENS=True, cada refresh bem-sucedido retorna um novo refresh token junto com o novo token de acesso. O refresh token anterior é consumido.
Sempre armazene o valor mais recente de refresh retornado por POST /user/login/refresh/. Se o seu cliente continuar reutilizando o refresh token original após a rotação, o segundo refresh retornará 401 Unauthorized e o usuário precisará fazer login novamente.
Um loop mínimo de refresh: 
import time, requests

def refreshed(refresh):
    response = requests.post(
        "https://api.dlpay.cloud/user/login/refresh/",
        json={"refresh": refresh},
    )
    data = response.json()
    return data["access"], data["refresh"], int(data["access_token_renew_interval"])

access, refresh, ttl = login(email, password)
expires_at = time.time() + ttl - 60

while True:
    if time.time() >= expires_at:
        access, refresh, ttl = refreshed(refresh)
        expires_at = time.time() + ttl - 60
    call_api(access)

​
Cadastro

POST /user/register/ cria um usuário e retorna o mesmo payload {access, refresh, access_token_renew_interval, user} do login, de modo que um cliente recém-cadastrado já está autenticado.

​
Chaves de API de seller

As chaves de API são emitidas por seller. Gerencie-as em /integrations/{seller_id}/apikeys/ — crie com Criar uma chave de API, liste com Listar chaves de API.

​
Formato

CampoTipoNotas
idUUIDIdentificador estável.
namestringRótulo legível por humanos.
descriptionstringNotas em formato livre.
keystring (UUID)O segredo propriamente dito.
activeboolChaves inativas são rejeitadas pela autenticação.
sellerUUIDO seller que esta chave autentica.
O valor de key é retornado pelos endpoints Criar e Recuperar, mas você deve tratá-lo como um segredo de gravação única na sua interface: copie-o no momento da criação, armazene-o no lado do servidor e nunca o registre em logs. Para rotacionar, exclua a chave antiga (Excluir uma chave de API) e crie uma nova.

​
Usando uma chave

curl "https://api.dlpay.cloud/sales/seller/$SELLER_ID/checkoutlink/" \
  -H "Authorization: Bearer $API_KEY"
As chaves de API funcionam apenas em endpoints configurados com a classe de autenticação combinada. Endpoints que usam a classe somente de usuário (a maioria dos endpoints de administração e gerenciamento de usuários) rejeitam chaves de API — eles exigem um JWT.

​
Controle de acesso: a tabela de acessos

O JWT sozinho diz quem é o chamador. Ele não diz sobre quais sellers esse usuário pode atuar. Esse mapeamento vive na tabela de acessos da plataforma:
ColunaAponta paraSignificado
userUsuárioO usuário ao qual o acesso é concedido.
sellerSellerO seller específico (opcional).
accountConta unificadaA conta unificada (opcional).
groupGrupoO grupo cujas permissões se aplicam a este acesso.
Um único usuário pode ter várias linhas na tabela de acessos — uma por seller/conta que ele administra. Cada linha associa o usuário a um grupo, e as permissões do grupo definem o que o usuário pode fazer para aquele seller específico. A própria tabela de acessos define três permissões customizadas:
CodenameUsada por
auth.manage_usersVerificação de permissão para gerenciar usuários
auth.manage_accessesVerificação de permissão para gerenciar acessos
auth.manage_groupsVerificação de permissão para gerenciar grupos
Estes são os codenames reais que a API utiliza ao validar permissões.

​
Bypass de superusuário

Toda verificação de permissão da plataforma retorna True imediatamente quando o usuário é superusuário. Superusuários podem chamar qualquer endpoint de gerenciamento independentemente da participação em grupos. Operadores de plataforma do dia a dia normalmente devem receber os grupos corretos em vez de serem promovidos a superusuários.

​
Gerenciar acessos pela API

O ciclo de vida completo está exposto sob o recurso de usuário: Os grupos em si ficam sob /groups/:

​
Verificações de permissão

Cada endpoint protegido declara uma ou mais verificações de permissão. Abaixo está o catálogo completo:
VerificaçãoRetorna True quando
É superusuárioO usuário é superusuário. Utilizada para proteger endpoints de administração da plataforma.
Pode gerenciar gruposO usuário é superusuário ou possui auth.manage_groups. Protege os endpoints CRUD de /groups/.
Pode gerenciar usuáriosO usuário é superusuário ou possui auth.manage_users. Protege os endpoints CRUD de /<user_id>/.
Pode gerenciar acessosPara list e retrieve (GETs somente leitura): qualquer usuário autenticado. Para escritas: o usuário é superusuário ou possui auth.manage_accesses. Protege os endpoints CRUD de acessos sob um usuário.
Outros endpoints exigem apenas autenticação padrão (qualquer usuário autenticado, JWT ou chave de API) — por exemplo, o endpoint que lista usuários vinculados a um seller.
O endpoint de acessos intencionalmente permite que qualquer usuário autenticado leia a lista de acessos. Isso é o que permite a um painel exibir “para quais sellers posso alternar?” sem exigir permissões elevadas. As operações de escrita no mesmo endpoint ainda exigem manage_accesses.

​
Endpoints públicos (sem autenticação)

Um pequeno conjunto de endpoints aceita intencionalmente tráfego anônimo. Eles servem superfícies públicas — páginas de checkout, formulários de cadastro, recuperação de senha, páginas públicas de assinatura — e estão configurados para permitir qualquer chamador, ou simplesmente não declaram classe de autenticação.
EndpointPropósito
POST /user/login/Emite o par de JWT. Veja Login.
POST /user/login/refresh/Rotaciona o refresh token, emite um novo access. Veja Refresh.
POST /user/register/Cadastro self-service. Veja Cadastro.
POST /user/passwordrecovery/request/Envia e-mail de recuperação. Veja Solicitar recuperação.
POST /user/passwordrecovery/perform/Resgata o token de recuperação. Veja Executar recuperação.
GET /event/event/{event_id}/Carrega o contexto público de um evento. Veja Contexto do evento.
POST /event/event/{event_id}/checkout/Cria um checkout a partir de uma página pública de evento. Veja Criar checkout.
GET /subscriptions/plan/{plan_id}/Carrega a página pública de um plano de assinatura. Veja Recuperar plano público.
POST /subscriptions/plan/{plan_id}/subscribe/Cria uma assinatura a partir de uma página pública de plano. Veja Assinar publicamente.
GET /subscriptions/subscriber/{subscriber_id}/Carrega o contexto público de um assinante. Veja Recuperar assinante público.
GET /subscriptions/subscriber/{subscriber_id}/payment/Histórico público de pagamentos de um assinante. Veja Listagem pública de pagamentos.
Todo o restante exige um cabeçalho Authorization válido.

​
Fluxo de recuperação de senha

O fluxo de recuperação é deliberadamente em duas etapas: solicitar um token de 6 dígitos por e-mail e, então, resgatá-lo com uma nova senha. Ambos os endpoints são públicos.
1

Solicite um token de recuperação

O usuário envia seu e-mail. O servidor consulta a conta, gera um token de 6 dígitos válido por 24 horas e o envia pelo template de e-mail password-recovery. O endpoint retorna 204 No Content independentemente de o e-mail corresponder ou não a um usuário — isso é intencional, para evitar vazar quais endereços estão cadastrados.
curl -X POST "https://api.dlpay.cloud/user/passwordrecovery/request/" \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@example.com"}'
Veja Recuperação de senha — solicitar.
2

Resgate o token com uma nova senha

O usuário envia o token de 6 dígitos recebido por e-mail junto com a nova senha. O servidor valida o token, atualiza a senha e exclui todas as linhas de recuperação pendentes para aquele usuário, de forma que o mesmo token não possa ser resgatado duas vezes.
curl -X POST "https://api.dlpay.cloud/user/passwordrecovery/perform/" \
  -H "Content-Type: application/json" \
  -d '{"token": "123456", "new_password": "new-strong-password"}'
Veja Recuperação de senha — executar.
3

Autentique o usuário

Após um resgate bem-sucedido, o usuário possui novas credenciais mas não tem sessão. Chame POST /user/login/ com a nova senha para obter um novo par de JWT.
Os tokens são inteiros de 6 dígitos (100000–999999). São válidos por 24 horas e são invalidados assim que um deles é resgatado com sucesso para o usuário. A proteção contra força bruta é responsabilidade da superfície chamadora — mantenha o formulário público atrás de rate limiting.