Autenticação e Acesso

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

Mecanismo	Emitido para	Formato do token	Identifica	Chamador típico
JWT (usuário)	Um usuário da plataforma	Dois JWTs curtos (`access`, `refresh`)	Um usuário real	Painel, ferramentas internas, qualquer backend agindo como uma pessoa
Chave de API (seller)	Um seller	Uma string UUID criada no painel	Uma conta de seller	Backend 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 token	Identidade resolvida	Credencial bruta
JWT válido	A instância de usuário correspondente (autenticado)	O JWT decodificado
Chave de API válida	Um 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álido	Usuário anônimo	Nenhuma

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âmetro	Valor
`ACCESS_TOKEN_LIFETIME`	1 dia
`REFRESH_TOKEN_LIFETIME`	4 dias
`ROTATE_REFRESH_TOKENS`	`True`

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": "..."}'

import requests

response = requests.post(
    "https://api.dlpay.cloud/user/login/",
    json={"email": "owner@example.com", "password": "..."},
)
data = response.json()
access = data["access"]
refresh = data["refresh"]
ttl = int(data["access_token_renew_interval"])

const response = await fetch("https://api.dlpay.cloud/user/login/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "owner@example.com", password: "..." }),
});
const { access, refresh, access_token_renew_interval } = await response.json();
const ttl = parseInt(access_token_renew_interval, 10);

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)

async function refreshed(refresh) {
  const r = await fetch("https://api.dlpay.cloud/user/login/refresh/", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ refresh }),
  });
  const data = await r.json();
  return {
    access: data.access,
    refresh: data.refresh,
    ttl: parseInt(data.access_token_renew_interval, 10),
  };
}

let { access, refresh, ttl } = await login(email, password);
let expiresAt = Date.now() / 1000 + ttl - 60;

setInterval(async () => {
  if (Date.now() / 1000 >= expiresAt) {
    ({ access, refresh, ttl } = await refreshed(refresh));
    expiresAt = Date.now() / 1000 + ttl - 60;
  }
}, 30_000);

curl -X POST "https://api.dlpay.cloud/user/login/refresh/" \
  -H "Content-Type: application/json" \
  -d "{\"refresh\": \"$REFRESH\"}"

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

Campo	Tipo	Notas
`id`	UUID	Identificador estável.
`name`	string	Rótulo legível por humanos.
`description`	string	Notas em formato livre.
`key`	string (UUID)	O segredo propriamente dito.
`active`	bool	Chaves inativas são rejeitadas pela autenticação.
`seller`	UUID	O 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"

import requests

requests.get(
    f"https://api.dlpay.cloud/sales/seller/{seller_id}/checkoutlink/",
    headers={"Authorization": f"Bearer {api_key}"},
)

await fetch(`https://api.dlpay.cloud/sales/seller/${sellerId}/checkoutlink/`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

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:

Coluna	Aponta para	Significado
`user`	Usuário	O usuário ao qual o acesso é concedido.
`seller`	Seller	O seller específico (opcional).
`account`	Conta unificada	A conta unificada (opcional).
`group`	Grupo	O 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:

Codename	Usada por
`auth.manage_users`	Verificação de permissão para gerenciar usuários
`auth.manage_accesses`	Verificação de permissão para gerenciar acessos
`auth.manage_groups`	Verificaçã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ção	Retorna `True` quando
É superusuário	O usuário é superusuário. Utilizada para proteger endpoints de administração da plataforma.
Pode gerenciar grupos	O usuário é superusuário ou possui `auth.manage_groups`. Protege os endpoints CRUD de `/groups/`.
Pode gerenciar usuários	O usuário é superusuário ou possui `auth.manage_users`. Protege os endpoints CRUD de `/<user_id>/`.
Pode gerenciar acessos	Para `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.

Endpoint	Propó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.

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"}'

import requests

requests.post(
    "https://api.dlpay.cloud/user/passwordrecovery/request/",
    json={"email": "owner@example.com"},
)

await fetch("https://api.dlpay.cloud/user/passwordrecovery/request/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "owner@example.com" }),
});

Veja Recuperação de senha — solicitar.

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"}'

import requests

requests.post(
    "https://api.dlpay.cloud/user/passwordrecovery/perform/",
    json={"token": "123456", "new_password": "new-strong-password"},
)

await fetch("https://api.dlpay.cloud/user/passwordrecovery/perform/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: "123456", new_password: "new-strong-password" }),
});

Veja Recuperação de senha — executar.

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.

Primeiros passos

Conceitos

Fluxos

Autenticação e Acesso

Os dois mecanismos

Qual devo usar?

Como os tokens são resolvidos

O que o contexto autenticado representa

Ciclo de vida do JWT

Refresh com rotação

Cadastro

Chaves de API de seller

Formato

Usando uma chave

Controle de acesso: a tabela de acessos

Bypass de superusuário

Gerenciar acessos pela API

Verificações de permissão

Endpoints públicos (sem autenticação)

Fluxo de recuperação de senha

​Os dois mecanismos

​Qual devo usar?

​Como os tokens são resolvidos

​O que o contexto autenticado representa

​Ciclo de vida do JWT

​Login

​Refresh com rotação

​Cadastro

​Chaves de API de seller

​Formato

​Usando uma chave

​Controle de acesso: a tabela de acessos

​Bypass de superusuário

​Gerenciar acessos pela API

​Verificações de permissão

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

​Fluxo de recuperação de senha

Os dois mecanismos

Qual devo usar?

Como os tokens são resolvidos

O que o contexto autenticado representa

Ciclo de vida do JWT

Login

Refresh com rotação

Cadastro

Chaves de API de seller

Formato

Usando uma chave

Controle de acesso: a tabela de acessos

Bypass de superusuário

Gerenciar acessos pela API

Verificações de permissão

Endpoints públicos (sem autenticação)

Fluxo de recuperação de senha