Authentication

Zquence supports two authentication models. For server-to-server tenant integrations, use API keys. They identify your tenant and environment for routes that explicitly support API-key access.

API keys (server-to-server)

Every API-key request includes your key pair as headers: Every request to a tenant-scoped endpoint must include your API key pair:

Header	Value
`x-api-key`	Your publishable key, e.g. `pk_live_...`
`x-api-secret`	Your secret key, e.g. `sk_live_...`
`Content-Type`	`application/json`

The tenant is resolved automatically from the key pair - you never pass tenantId in the URL or body. Each key is bound to one environment and a set of scopes. A request must satisfy both the key scope and the tenant role permission enforced by the endpoint. A key with sanctions.read, for example, cannot submit a screen or record a decision.

Key types

Prefix	Purpose	Where it’s safe
`pk_live_...` / `pk_test_...`	Publishable key. Identifies your tenant.	OK to ship in clients, logs, frontend code.
`sk_live_...` / `sk_test_...`	Secret key. Authenticates the request.	Server-side only. Never ship to browsers or mobile apps.

The _live_ / _test_ segment is set when the key is created and reflects the environment the key belongs to. Keys created in a live environment get _live_; keys created in a sandbox environment get _test_. The mode is baked into the key string so you can tell at a glance whether a leaked credential touches production data.

If a secret key leaks, rotate it immediately in the dashboard and redeploy. Requests signed with the rotated secret will fail with 401 authentication_error.

Example

curl https://api.zquence.ai/v1/tenants/add-user \
  -H "x-api-key: pk_live_51H..." \
  -H "x-api-secret: sk_live_51H..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada", "email": "ada@example.com", "phone": "+14155552671"}'

const res = await fetch("https://api.zquence.ai/v1/tenants/add-user", {
  method: "POST",
  headers: {
    "x-api-key":    process.env.ZQUENCE_PUBLIC_KEY!,
    "x-api-secret": process.env.ZQUENCE_SECRET_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Ada", email: "ada@example.com", phone: "+14155552671" }),
});
const user = await res.json();

User sessions (dashboard & end-user flows)

The dashboard and user-facing flows (hosted KYC, escrow acceptance) authenticate users with short-lived JWTs plus a session cookie. You don’t manage these directly - they’re issued by /auth/login and refreshed automatically by the dashboard.

If you’re building a customer-facing app that needs a user session, use Single Sign-On below rather than hand-rolling the JWT flow.

Single Sign-On (SSO)

For platforms that want to delegate authentication to their own identity provider, Zquence supports SAML 2.0 and OIDC. Contact sales to enable SSO on your tenant. Once enabled, your users are minted a Zquence session from your IdP - no password management on our side.

Which auth do I use?

You’re calling…	Use
Documented tenant external API routes (your backend to our API)	API keys
Dashboard/admin-console management routes	User session or SSO
The dashboard at `app.zquence.ai`	Your Zquence login (or SSO)
Webhook signature verification	Webhook signing secret (different from API keys)

Rotating keys

Keys should be rotated on a schedule and immediately after any suspected exposure.

Create the new key

Create a new key pair in the dashboard.

Deploy the new key alongside the old

Update your secrets manager. Keep the old key live so in-flight requests don’t fail.

Revoke the old key

Revoke the old key pair in the dashboard.

Use one key per environment and per service. Fine-grained keys make revocation painless - you only break the one caller.

Start here

Integration basics

API keys (server-to-server)

Key types

Example

User sessions (dashboard & end-user flows)

Single Sign-On (SSO)

Which auth do I use?

Rotating keys

​API keys (server-to-server)

​Key types

​Example

​User sessions (dashboard & end-user flows)

​Single Sign-On (SSO)

​Which auth do I use?

​Rotating keys

API keys (server-to-server)

Key types

Example

User sessions (dashboard & end-user flows)

Single Sign-On (SSO)

Which auth do I use?

Rotating keys