Saltar al contenido principal

Autenticación

Ishtaran tiene tres principals de autenticación separados. Autentican actores distintos, llevan alcances distintos, y nunca son intercambiables — una credencial válida para uno es rechazada de inmediato por las rutas que exigen otro.

1. Application API Key​

Qué es: una credencial machine-to-machine, una por Environment (sandbox/production), generada vía POST /v1/environments/{environmentId}/api-keys. Ver Organization, Application y Environment para cómo se delimita.

Cómo enviarla: el header HTTP X-Api-Key.

A quién representa: tu backend, no una persona. Es la credencial que casi todo ejemplo de código de este sitio usa — es lo que IshtaranClient.create({ apiKey: ... }) (o el constructor equivalente en cada SDK) recibe.

Nunca la pongas en código de frontend o mobile. Es una credencial bearer con todos los permisos de su Environment — trátala exactamente como una contraseña de base de datos, inyectada solo del lado del servidor.

2. Member JWT​

Qué es: el token de sesión de un usuario humano de tu Organization (alguien con login en el control plane de la plataforma), obtenido vía POST /v1/auth/login.

Cómo enviarlo: el header estándar Authorization: Bearer <token>.

A quién representa: una persona, para operaciones de control plane y algunas operaciones específicamente restringidas. Un puñado de rutas exige explícitamente una sesión de Member y rechaza una API Key aunque se proporcione una — por ejemplo accounts.authorizeApplication/freeze/unfreeze/close/revokeRelationship, y gestionar WebhookEndpoints (Permissions.WebhookEndpointManage, ver Webhooks § Configuración). Si la página de referencia de una ruta no dice que la API Key funciona, asume que necesita un Member JWT.

3. AccountHolder JWT​

Qué es: el token de sesión de tu cliente final — la persona que la plataforma llama AccountHolder, no el staff de tu propia Organization. Obtenido vía accountHolders.signUp/login, o vía signUpAndClaimInvitation al aceptar una invitación a una relación de AccountHolder ya existente.

A quién representa: un individuo con identidad propia, aislado del contexto de Member/API Key de tu Organization. Este es un contexto de autenticación tercero e independiente — nunca derivado de, ni convertible a, una API Key o un Member JWT, y su token de sesión nunca se comparte con client.auth (Member) en la misma instancia del client, incluso dentro del mismo proceso del SDK.

Úsalo cuando tus usuarios finales necesiten actuar por su cuenta (ej.: ver su propio saldo, aceptar una invitación) en vez de actuar a través de tu backend en su nombre vía API Key.

Resumen​

API Key         != Member JWT      != AccountHolder JWT
(tu backend)        (tu equipo)        (tu cliente final)

Ninguno de los tres es un superconjunto del otro — cada uno abre una puerta distinta, deliberadamente separada. Las operaciones administrativas del Platform Owner (internas a Ishtaran) usan un cuarto mecanismo totalmente aparte (rutas /v1/admin/*) que no forma parte de la superficie de integración pública — ver Sandbox para lo que está disponible a integradores en Sandbox.