Authentication and scopes

Assayra has three deliberately separate credential classes.

Credential	Audience	Transport	Use
Tenant API key	Customer backend	Bearer pl_sandbox_… or pl_live_…	Applications, workflows, webhooks and entitled tenant APIs
Operator session	Client Admin Portal	Secure, HTTP-only cookie	Human administration and case work
Invitation token	One applicant journey	URL path issued by Assayra	Only the specific application and permitted public steps

Control Tower workforce credentials are not tenant credentials and are not part of the public tenant API contract.

API keys

Send the key in the bearer header:

Authorization: Bearer pl_sandbox_REPLACE_ME

Do not place API keys in browser bundles, mobile apps, URLs, query parameters or logs. Your backend should exchange its own authenticated user action for a narrowly scoped Assayra call.

Choose the smallest scope

Common integration scopes include:

Scope	Grants
workflows:read	Read workflow IDs, application types and published status
applications:write	Create applications and manage invitations
applications:read	Read application status and verification results
cases:read	Read entitled review/case records
fraud:write	Submit transaction/account events for scoring
fraud:read	Read fraud results and alerts
webhooks:write	Create, rotate and disable event endpoints
webhooks:read	Inspect endpoint and delivery state

The Developer Hub shows the authoritative scope catalogue for the tenant and plan. Unknown, disabled or unentitled scopes are rejected.

Key lifecycle

1. Issue a key for one integration and environment.
2. Copy the one-time secret into a managed secret store.
3. Record the visible prefix in your runbook.
4. Test the narrow scopes.
5. Rotate by creating the successor, deploying it, verifying usage, then revoking the predecessor.

Revocation is immediate. There is no recovery endpoint for a secret because Assayra does not retain the recoverable value.

The environment is part of the credential itself:

• pl_sandbox_… creates and reads Sandbox applications.
• pl_live_… creates and reads Live applications.

Changing the active environment in Client Admin Portal does not change an existing key. Issue a separate key after switching to Live, store the one-time secret immediately, and keep both credentials in separate secret-manager entries.

Example backend client

import { Assayra } from "@assayra/sdk-web";

const assayra = new Assayra({
  baseUrl: process.env.ASSAYRA_BASE_URL!,
  token: process.env.ASSAYRA_API_KEY!,
});

const { applications } = await assayra.applications.list();

One environment, one credential.

Never reuse sandbox keys in production or share a single key between unrelated services. Separate keys make scope, rotation, audit and incident response precise.

Authentication failures

• 401 — missing, malformed, expired, revoked or invalid credential.
• 403 — valid principal without the required role, scope, tenant entitlement or state.
• 404 — may intentionally hide a cross-tenant or inaccessible record.

See errors and idempotency for the common response envelope.