paybondpaybond
Sign in

Authentication & tenant binding

How Paybond derives tenant scope from credentials and how Kit sessions preserve that boundary automatically.

Paybond is tenant-scoped by design. The authenticated credential determines which tenant a request belongs to, and the SDK preserves that boundary for every Harbor and Signal call. New API keys expose their intended environment in the prefix. Gateway still derives the authoritative environment from storage and rejects a visible live/sandbox prefix that does not match the tenant row.

  1. Your runtime holds a service-account API key (paybond_sk_live_… or paybond_sk_sandbox_…) issued for a single tenant realm. For local sandbox setup, use npx -p @paybond/kit paybond login or paybond-kit-login. Production keys are created in Console and stored in your deployment secret manager. Keys must carry the environment prefix (paybond_sk_live_… / paybond_sk_sandbox_…).
  2. The Kit calls the hosted Gateway GET /v1/auth/principal with that key to resolve the tenant realm and environment.
  3. The Kit sends Harbor, Signal, fraud, protocol, and A2A calls through Gateway with the same API key.
  4. Gateway derives upstream service credentials internally; SDK callers do not configure Harbor origins or manage Harbor JWTs.

Device login

The login CLIs use browser approval to mint one sandbox operator service-account key for a single tenant:

npx -p @paybond/kit paybond login
paybond-kit-login

A tenant admin approves the request in Console. Sandbox approvals bind to the admin's sandbox, or to the sandbox paired to their active live tenant. The minted key is always an operator key and the browser never receives the raw API key. Device login does not mint production keys.

By default the CLIs write PAYBOND_API_KEY=... to .env.local with file mode 0600. For the default .env.local target, they add .env.local to .gitignore when needed. For custom env-file paths inside a git repo, they refuse to write unless the target is already ignored. They refuse to overwrite an existing PAYBOND_API_KEY unless --force is passed. After writing, output is limited to a masked key identity and the target sandbox tenant.

What the SDK handles for you

  • Tenant discovery from Gateway.
  • Tenant binding on Harbor, Signal, fraud, and protocol requests.
  • Protection against reusing one session across multiple tenants by accident.
  • Failure when a response does not match the tenant or intent you asked for.

Language entry points

Session lifecycle

  • If you rotate an API key, create a new session object and drain in-flight work on the old one.
  • Never reuse a Harbor client or Kit session across tenants.
  • Always close sessions when your application or worker is done with them.

Design guidelines

  • Do not treat request bodies, query parameters, or local config as the source of tenant truth.
  • Do not build your own tenant header conventions when the SDK already derives the correct context.
  • Use one session per tenant, per environment, per credential set.