Autenticação

A Ishtaran tem três principals de autenticação separados. Eles autenticam atores diferentes, carregam escopos diferentes, e nunca são intercambiáveis — uma credencial válida para um é rejeitada de cara pelas rotas que exigem outro.

1. Application API Key

O que é: uma credencial machine-to-machine, uma por Environment (sandbox/production), gerada via POST /v1/environments/{environmentId}/api-keys. Veja Organization, Application e Environment para como ela é escopada.

Como enviar: o header HTTP X-Api-Key.

Quem representa: seu backend, não uma pessoa. É a credencial que quase todo exemplo de código neste site usa — é o que IshtaranClient.create({ apiKey: ... }) (ou o construtor equivalente em cada SDK) recebe.

Nunca coloque em código de frontend ou mobile. É uma credencial bearer com todas as permissões do seu Environment — trate exatamente como uma senha de banco de dados, injetada só no lado do servidor.

2. Member JWT

O que é: o token de sessão de um usuário humano da sua Organization (alguém com login no control plane da plataforma), obtido via POST /v1/auth/login.

Como enviar: o header padrão Authorization: Bearer <token>.

Quem representa: uma pessoa, para operações de control plane e algumas operações especificamente restritas. Um punhado de rotas exige explicitamente uma sessão de Member e rejeita uma API Key mesmo que uma seja fornecida — por exemplo accounts.authorizeApplication/freeze/unfreeze/close/revokeRelationship, e gerenciar WebhookEndpoints (Permissions.WebhookEndpointManage, veja Webhooks § Configuração). Se a página de referência de uma rota não disser que API Key funciona, presuma que ela precisa de um Member JWT.

3. AccountHolder JWT

O que é: o token de sessão do seu cliente final — a pessoa que a plataforma chama de AccountHolder, não a equipe da sua própria Organization. Obtido via accountHolders.signUp/login, ou via signUpAndClaimInvitation ao aceitar um convite para um relacionamento de AccountHolder já existente.

Quem representa: um indivíduo com identidade própria, isolado do contexto de Member/API Key da sua Organization. Este é um contexto de autenticação terceiro e independente — nunca derivado de, ou conversível para, uma API Key ou um Member JWT, e o token de sessão dele nunca é compartilhado com client.auth (Member) na mesma instância do client, mesmo dentro do mesmo processo do SDK.

Use isso quando seus usuários finais precisarem agir por conta própria (ex.: ver o próprio saldo, aceitar um convite) em vez de agir através do seu backend em nome deles via API Key.

Resumo

API Key       != Member JWT       != AccountHolder JWT
(seu backend)    (sua equipe)        (seu cliente final)

Nenhum dos três é um superconjunto do outro — cada um abre uma porta diferente, deliberadamente separada. Operações administrativas do Platform Owner (internas à Ishtaran) usam um quarto mecanismo totalmente à parte (rotas /v1/admin/*) que não faz parte da superfície de integração pública — veja Sandbox para o que está disponível a integradores no Sandbox.