> ## Documentation Index > Fetch the complete documentation index at: https://userepass.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Autenticação > Autentique requisições com chaves de API e entenda organizações e papéis. 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: Envie a chave no header `Authorization` com o esquema `Bearer`. O valor deve incluir o prefixo `rstr_` literal. ```bash theme={null} curl https://api.userepass.com/me \ -H "Authorization: Bearer rstr_a1b2c3d4e5f6g7h8i9j0k1l2" ``` Envie a chave no header `x-api-key`. ```bash theme={null} 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`: ```json theme={null} { "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](/docs/convencoes/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`: ```json theme={null} { "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. ```mermaid theme={null} sequenceDiagram participant Sistema as Sistema integrador participant API as API Repass participant Auth as Camada de autorização participant Org as Organização Sistema->>API: POST /reprocess (Authorization: Bearer rstr_...) API->>Auth: resolve usuário dono da chave + organização Auth->>Org: papel do dono nesta organização? Org-->>Auth: owner | admin | member alt papel ∈ {owner, admin} Auth-->>API: autorizado → executa a operação API-->>Sistema: 200 else member ou sem vínculo Auth-->>Sistema: 403 not_allowed end ``` ### 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](/docs/conceitos/reprocessamento). * **Escritas financeiras de payout**: executar, retentar, cancelar runs de payout e definir a política de payouts. Veja [Payouts](/docs/conceitos/payouts). * **Operações fiscais sensíveis**: validar ou rejeitar uma nota fiscal, baixar o documento e definir a política fiscal. Veja [Fiscal](/docs/conceitos/fiscal). * **Publicação de termos**: publicar uma nova versão dos termos do programa. Veja [Termos](/docs/conceitos/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: ```json theme={null} { "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. ```bash cURL theme={null} curl https://api.userepass.com/me \ -H "Authorization: Bearer rstr_a1b2c3d4e5f6g7h8i9j0k1l2" ``` ```json theme={null} { "id": "user_01J...", "name": "Integração ERP", "email": "integracao@exemplo.com.br", "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 Crie uma chave dedicada para cada sistema integrador, com um nome descritivo. Isso facilita revogar uma única integração sem afetar as demais. 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 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. 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 Faça sua primeira requisição autenticada de ponta a ponta. Entenda os identificadores opacos com prefixo (`prog_`, `aff_`, `conv_`...). O envelope único de erro e os códigos `401`/`403` desta página. Repita POSTs com segurança usando o header `Idempotency-Key`.