Autenticação

A API da Repass é multi-tenant: toda operação roda sob exatamente uma organização (o tenant) e é autorizada pelo papel do membro nessa organização. Para integrações server-to-server (S2S), você autentica com uma chave de API com prefixo rstr_, enviada em um de dois headers. Esta página cobre como autenticar, como o multi-tenancy funciona e como os papéis controlam o que cada chave pode fazer.

A base URL de produção é https://api.userepass.com. As chaves de API são o meio recomendado para integrações automatizadas; operadores humanos usam login por sessão no painel (fora do escopo desta referência de API).

Chaves de API

Toda chave de API gerada na Repass tem o prefixo rstr_ (por exemplo, rstr_a1b2c3d4...). A chave é exibida uma única vez no momento da criação: copie e guarde em local seguro, pois ela não pode ser recuperada depois.

Trate a chave de API como um segredo. Ela concede acesso total ao papel do usuário dono dentro da organização. Nunca a exponha em código cliente (navegador, app móvel), em repositórios públicos ou em logs. Se uma chave vazar, revogue-a imediatamente e gere uma nova. Use sempre HTTPS.

Dois modos de envio

Você pode enviar a chave de duas formas equivalentes. Use uma delas por requisição:

Authorization: Bearer
x-api-key

Envie a chave no header Authorization com o esquema Bearer. O valor deve incluir o prefixo rstr_ literal.

curl https://api.userepass.com/me \
  -H "Authorization: Bearer rstr_a1b2c3d4e5f6g7h8i9j0k1l2"

Envie a chave no header x-api-key.

curl https://api.userepass.com/me \
  -H "x-api-key: rstr_a1b2c3d4e5f6g7h8i9j0k1l2"

Os dois headers autenticam o mesmo usuário e resultam no mesmo contexto de autorização. A requisição é tratada como autenticada por chave de API quando há um header x-api-key ou um Authorization: Bearer rstr_... (com o prefixo rstr_ literal). Um Bearer sem o prefixo rstr_ não é reconhecido como chave de API.

Chave inválida ou ausente

Uma requisição sem credencial válida (sem header, com uma chave desconhecida rstr_invalida ou expirada) recebe 401:

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

Uma chave desconhecida é tratada como “não autenticado”: você sempre recebe 401, nunca um erro vazado do provedor de autenticação. Veja a referência de erros para o envelope completo.

Limite de requisições

Cada chave de API tem um limite de requisições próprio, habilitado por padrão. O limite padrão é de 10 requisições por janela de 24 horas por chave. Janelas e cotas maiores podem ser configuradas por chave conforme a necessidade da integração.

Multi-tenancy por organização

A organização é a fronteira de isolamento de dados da plataforma. Todo recurso (programas, afiliados, links, conversões, comissões, payouts) pertence a exatamente uma organização, e nenhuma consulta cruza organizações. Você não passa o organizationId explicitamente nas requisições: ele é resolvido a partir da sua credencial. Quando uma chave de API pertence a um usuário que está em exatamente uma organização, essa é a organização da requisição. Se o dono pertencer a mais de uma organização sem uma organização ativa definida, a API recusa a operação com 403:

{
  "error": {
    "type": "permission_error",
    "code": "not_allowed",
    "message": "Multiple organizations available; set an active organization first"
  }
}

Se o dono não pertencer a nenhuma organização, a resposta também é 403, com a mensagem User does not belong to any organization.

A prática recomendada para integrações S2S é dedicar cada chave de API a um usuário vinculado a uma única organização. Assim a organização da requisição é sempre determinística, sem ambiguidade.

Papéis e autorização

Dentro de uma organização, cada membro tem um papel que determina quais operações de escrita pode realizar:

Papel	Descrição	Pode operações `admin+`?
`owner`	Dono da organização (quem a criou).	Sim
`admin`	Administrador da organização.	Sim
`member`	Membro operacional (papel padrão ao entrar).	Não

owner é atribuído automaticamente a quem cria a organização. Ao entrar em uma organização sem papel explícito, o membro nasce como member.

A chave herda o papel do dono

Uma chave de API não tem papel próprio. A autorização usa o papel do usuário dono da chave na organização. Se o dono é admin, a chave pode executar operações administrativas; se é member, a chave fica restrita às operações que não exigem admin+. Promover ou rebaixar o usuário dono altera, na mesma medida, o que a chave pode fazer.

Operações que exigem `admin+`

A maioria das leituras e escritas operacionais aceita qualquer membro autenticado. Algumas operações sensíveis exigem papel owner ou admin:

Reprocessamento: disparar jobs que recalculam comissões após mudança de regra. Veja Reprocessamento.
Escritas financeiras de payout: executar, retentar, cancelar runs de payout e definir a política de payouts. Veja Payouts.
Operações fiscais sensíveis: validar ou rejeitar uma nota fiscal, baixar o documento e definir a política fiscal. Veja Fiscal.
Publicação de termos: publicar uma nova versão dos termos do programa. Veja Termos.

Quando o papel é insuficiente (ou não há vínculo com a organização), a API responde 403, com uma mensagem que lista os papéis aceitos pela operação:

{
  "error": {
    "type": "permission_error",
    "code": "not_allowed",
    "message": "This action requires one of the roles: owner, admin"
  }
}

Verificando sua credencial

O endpoint GET /me retorna o perfil do usuário autenticado e é a forma mais simples de confirmar que sua chave funciona e identifica o dono correto.

curl https://api.userepass.com/me \
  -H "Authorization: Bearer rstr_a1b2c3d4e5f6g7h8i9j0k1l2"

{
  "id": "user_01J...",
  "name": "Integração ERP",
  "email": "[email protected]",
  "image": null,
  "role": null,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-06-13T09:30:00.000Z"
}

O campo role da resposta de /me é o papel global de plataforma do usuário (normalmente null); ele não reflete o papel do membro (owner/admin/member) dentro da organização, que é o que governa a autorização das operações de escrita.

Para a estrutura completa de qualquer endpoint, veja a aba Referência da API.

Boas práticas

Uma chave por integração

Crie uma chave dedicada para cada sistema integrador, com um nome descritivo. Isso facilita revogar uma única integração sem afetar as demais.

Princípio do menor privilégio

Vincule a chave a um usuário dono cujo papel seja o mínimo necessário. Se a integração só faz leitura e ingestão de conversões, um usuário member é suficiente. Reserve admin+ para integrações que de fato precisam reprocessar, gerenciar payouts ou validar notas fiscais.

Rotacione e revogue

Rotacione chaves periodicamente e revogue imediatamente qualquer chave suspeita de vazamento. Como a chave herda o papel do dono, uma chave administrativa vazada tem amplo poder de escrita.

Sempre HTTPS, nunca no cliente

Envie a chave somente por HTTPS e somente a partir de um servidor que você controla. Nunca embuta a chave em código que roda no navegador ou em apps móveis.

Próximos passos

Quickstart

Faça sua primeira requisição autenticada de ponta a ponta.

IDs e recursos

Entenda os identificadores opacos com prefixo (prog_, aff_, conv_…).

Erros

O envelope único de erro e os códigos 401/403 desta página.

Idempotência

Repita POSTs com segurança usando o header Idempotency-Key.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Autenticação

Chaves de API

Dois modos de envio

Chave inválida ou ausente

Limite de requisições

Multi-tenancy por organização

Papéis e autorização

A chave herda o papel do dono

Operações que exigem `admin+`

Verificando sua credencial

Boas práticas

Próximos passos

Quickstart

IDs e recursos

Erros

Idempotência

​Chaves de API

​Dois modos de envio

​Chave inválida ou ausente

​Limite de requisições

​Multi-tenancy por organização

​Papéis e autorização

​A chave herda o papel do dono

​Operações que exigem admin+

​Verificando sua credencial

​Boas práticas

​Próximos passos

Quickstart

IDs e recursos

Erros

Idempotência

Chaves de API

Dois modos de envio

Chave inválida ou ausente

Limite de requisições

Multi-tenancy por organização

Papéis e autorização

A chave herda o papel do dono

Operações que exigem `admin+`

Verificando sua credencial

Boas práticas

Próximos passos