Skip to main content

Authentication

Ishtaran has three separate authentication principals. They authenticate different actors, carry different scopes, and are never interchangeable — a credential valid for one is rejected outright by routes that require another.

1. Application API Key​

What it is: a machine-to-machine credential, one per Environment (sandbox/production), generated via POST /v1/environments/{environmentId}/api-keys. See Organization, Application, and Environment for how it's scoped.

How to send it: the X-Api-Key HTTP header.

Who it represents: your backend, not a person. This is the credential almost every code example on this site uses — it's what IshtaranClient.create({ apiKey: ... }) (or the equivalent constructor in each SDK) takes.

Never put it in frontend or mobile code. It's a bearer credential with the full permissions of its Environment — treat it exactly like a database password, injected server-side only.

2. Member JWT​

What it is: the session token for a human user of your Organization (someone with a login on the platform's control plane), obtained via POST /v1/auth/login.

How to send it: the standard Authorization: Bearer <token> header.

Who it represents: a person, for control-plane and a few specifically-gated operations. A handful of routes explicitly require a Member session and reject an API Key even if one is provided — for example accounts.authorizeApplication/freeze/unfreeze/close/ revokeRelationship, and managing WebhookEndpoints (Permissions.WebhookEndpointManage, see Webhooks § Configuration). If a route's reference page doesn't say API Key works, assume it needs a Member JWT.

3. AccountHolder JWT​

What it is: the session token for your end customer — the person the platform calls an AccountHolder, not your own Organization's staff. Obtained via accountHolders.signUp/login, or via signUpAndClaimInvitation when accepting an invitation to an existing AccountHolder relationship.

Who it represents: an individual end user with their own identity, isolated from your Organization's Member/API Key context. This is a third, independent authentication context — never derived from, or convertible to, an API Key or a Member JWT, and its session token is never shared with client.auth (Member) on the same client instance even within the same SDK process.

Use this when your end users need to act on their own behalf (e.g. see their own balance, claim an invitation) rather than through your backend acting on their behalf via the API Key.

Summary​

API Key       != Member JWT       != AccountHolder JWT
(your backend)   (your staff)        (your end customer)

None of the three is a superset of another — each opens a different, deliberately separate door. Platform Owner (Ishtaran-internal) administrative operations use a fourth mechanism entirely (/v1/admin/* routes) that is not part of the public integration surface — see Sandbox for what's available to integrators in Sandbox.