Authentication — secret, publishable, and client session keys

Jaza uses two long-lived keys plus a short-lived client session from your host handshake. Top-up JWTs are minted by the client SDK from that session — you do not pass them through onRequestToken on the happy path.

Keys

Key	Prefix (sandbox / live)	Where
Secret	`jz_test_sk_…` / `jz_live_sk_…`	Server only — `@jazadev/node`
Publishable	`jz_test_pk_…` / `jz_live_pk_…`	Client app

Backend

Node

import { Jaza } from '@jazadev/node';

const jaza = new Jaza({
  secretKey: process.env.JAZA_SECRET_KEY!,
  publicKey: process.env.JAZA_PUBLIC_KEY!,
});

Frontend

React Native
React

Pass the publishable key into JazaProvider:

<JazaProvider
  publishableKey={process.env.EXPO_PUBLIC_JAZA_PUBLISHABLE_KEY!}
  getSession={async () => { /* POST /api/jaza/init */ }}
/>

Pass the publishable key into JazaProvider:

<JazaProvider
  publishableKey={process.env.NEXT_PUBLIC_JAZA_PUBLISHABLE_KEY!}
  getSession={async () => { /* POST /api/jaza/init */ }}
/>

Never embed the secret key in a mobile app, web frontend, or public repository.

Client session JWT

jaza.init({ customerId }) returns an InitResult with sessionToken. Your app loads it via JazaProvider getSession (or authEndpoint). The client SDK then calls Jaza client routes with:

X-Jaza-Public-Key: <publishable key>
Authorization: Bearer <session JWT>

See Handshake.

Top-up JWT (internal)

After a session exists, the SDK mints a short-lived top-up JWT via POST /v1/client/top-ups when the user opens checkout. Apps do not implement onRequestToken for the primary flow.

Advanced / legacy

jaza.topUp({ customerId }) on the Node SDK still returns a host-minted top-up JWT for older integrations. Prefer the client-session path above.

Webhook secrets

Endpoint signing secrets (whsec_…) are separate from API keys. Store them only on the server and verify with jaza.webhooks.constructEvent. See Webhooks.

Environments

Sandbox and live are isolated (keys, wallets, top-ups, webhooks, customers). Use test keys until the flow is solid, then switch to live keys from the dashboard.

Going live: remint `customerId`

A cus_… created with jz_test_* keys does not exist under jz_live_*. jaza.init / getCustomer return 404 Customer not found. Balances and ledger do not carry over. Your host app owns the mapping. Typical pattern when a stored id is missing in the current environment:

Detect 404 on getCustomer / init (or compare stored env vs current key prefix).
Call createCustomer with the same email/phone against the live secret key.
Overwrite the user’s customerId in your database.
Call jaza.init with the new id.

import { Jaza, JazaError } from '@jazadev/node';

async function ensureLiveCustomer(user: {
  id: string;
  email: string;
  phone?: string;
  jazaCustomerId?: string;
}) {
  try {
    if (user.jazaCustomerId) {
      await jaza.getCustomer(user.jazaCustomerId);
      return user.jazaCustomerId;
    }
  } catch (err) {
    if (!(err instanceof JazaError) || err.statusCode !== 404) throw err;
  }

  const customer = await jaza.createCustomer({
    name: user.email.split('@')[0] ?? 'User',
    email: user.email,
    phoneNumber: user.phone,
  });
  await db.users.update(user.id, { jazaCustomerId: customer.id });
  return customer.id;
}

On the client, handle handshake failure via onAuthError(error) and show authError from useJaza(). Navigate away before clearing session so screens that call useJaza are not left outside JazaProvider.

Next steps

Quickstart · Handshake · Top-up · Node SDK

Get started

Core concepts

Guides

SDKs

Reference

Authentication — secret, publishable, and client session keys

Keys

Backend

Frontend

Client session JWT

Top-up JWT (internal)

Advanced / legacy

Webhook secrets

Environments

Going live: remint `customerId`

Next steps

​Keys

​Backend

​Frontend

​Client session JWT

​Top-up JWT (internal)

​Advanced / legacy

​Webhook secrets

​Environments

​Going live: remint customerId

​Next steps

Keys

Backend

Frontend

Client session JWT

Top-up JWT (internal)

Advanced / legacy

Webhook secrets

Environments

Going live: remint `customerId`

Next steps