API keys and authentication

ArcenPay separates credentials by trust boundary, environment, and capability. This reference explains every credential type, which credentials work with which API endpoints, and how the SDKs authenticate for you. Read this page before wiring up your first integration — most integration issues come from using the wrong credential on the wrong endpoint.

Base URL

All REST endpoints are mounted under https://api.arcenpay.com/api/v1. There is no controller at the bare /v1 path; https://api.arcenpay.com/v1/* issues a 308 redirect to /api/v1/*. GET https://api.arcenpay.com/health is unauthenticated and returns 200 when the service is up.

The credentials that can authenticate a request

Credential	Prefix / format	Where it belongs	Purpose
Secret key	`sk_live_…` / `sk_test_…`	Server only	`ArcenClient` (Node SDK), privileged client-safe REST calls, temporary-token minting
Restricted key	`rk_live_…` / `rk_test_…`	Server only	Same as a secret key, limited to the permissions you grant
Publishable key	`pk_live_…` / `pk_test_…`	Browser	`ArcenPayProvider` (React SDK), read-only client-safe endpoints + identifying a customer for the embed
Embed access token	`arc_tok_…` or signed JWT	Browser / embed	Company-scoped session (default 10 minutes) minted server-side for `ArcenEmbed`
Webhook signing secret	`whsec_…`	Your server	HMAC-SHA256 verification of incoming webhook payloads
Dashboard session	`arcen_session` cookie	Browser	Dashboard access with team-role RBAC — created after email OTP or SIWE wallet auth
Facilitator secret	`FACILITATOR_SECRET`	Platform ops	Internal billing-event ingestion and maintenance endpoints

The legacy api_… key prefix has been removed from the platform. Existing api_… keys no longer authenticate anywhere. Regenerate any old keys as sk_… (secret), rk_… (restricted), or pk_… (publishable) in the dashboard — the raw value is shown once at creation.

Key prefixes and environments

The middle part of a key prefix encodes the environment the key was created for:

sk_live_…, pk_live_…, rk_live_… → created in a Production workspace environment.
sk_test_…, pk_test_…, rk_test_… → created in a Development workspace environment.

Keys are scoped to the workspace environment in which they were created. A sk_test_… key can only access the team’s development catalog and customers; a sk_live_… key can only access production.

Secrets from development and production are separate. Do not share *_test_* keys into production services, and never put *_live_* keys into test/staging environments where they might be logged or exposed.

Which key works where — the endpoint auth matrix

This is the most important table on this page. It tells you exactly which credential each endpoint group accepts today.

Endpoint group	Example endpoints	Secret `sk_`	Restricted `rk_`	Publishable `pk_`	Embed token (JWT/`arc_tok_`)	Dashboard session
Entitlement reads	`GET /api/v1/check`, `GET /api/v1/entitlements`, `GET /api/v1/flags/check`	✅	✅	✅	✅	❌
Usage consumption	`POST /api/v1/usage/consume`	✅	✅	✅	✅	❌
Temporary token minting	`POST /api/v1/api-keys/tokens`	✅ with `tokens.create`	✅ with `tokens.create`	❌	❌	❌
zkTLS proofs	`GET/POST /api/v1/proofs/zktls`	✅	✅	✅	❌	❌
Customer / company management	`GET/POST /api/v1/companies`, `GET/PATCH/DELETE /api/v1/companies/:id`	✅	✅	❌	❌	✅
Events (track / identify)	`POST /api/v1/events`	✅	✅	✅	✅	✅
Payment links	`GET/POST /api/v1/payment-links`, `GET/PATCH /api/v1/payment-links/:id`	✅	✅	❌	❌	✅
Checkout sessions	`GET/POST /api/v1/checkout-sessions`, `GET /api/v1/checkout-sessions/:id`	✅	✅	❌	❌	✅
Coupon validation	`GET /api/v1/coupons/validate`	✅	✅	✅	✅	✅
Subscription activation	`POST /api/v1/subscriptions/activate`	✅	✅	❌	✅	✅
Embed token minting (identify)	`POST /api/v1/access-tokens`	✅	✅	❌	❌	✅
Company lifecycle	`POST /api/v1/companies/plan`, `POST /api/v1/companies/unsubscribe`, `POST /api/v1/companies/resume`	❌	❌	❌	✅	❌
Company overrides	`GET/POST/DELETE /api/v1/companies/:id/overrides`	✅	✅	❌	❌	✅
Catalog management	`/api/v1/catalog/plans`, `/add-ons`, `/credits`, `/config`, `/publish`	❌	❌	❌	❌	✅ (dashboard roles only)
Invoices	`/api/v1/invoices …`	✅ (with `invoices.*`/`payments.write`)	✅ (with `invoices.*`/`payments.write`)	❌	❌	✅ (dashboard roles only)
Environments	`/api/v1/environments`	❌	❌	❌	❌	✅ (dashboard roles only)
Webhook config	`/api/v1/provider/webhooks`, `/webhooks/secret`, `/webhooks/test`	❌	❌	❌	❌	✅ (OWNER/ADMIN only)
Audit log	`GET /api/v1/audit-log`	❌	❌	❌	❌	✅ (`audit:read` role)
Agent config & dispatch	`GET/PUT /api/v1/agent/permissions`, `GET/POST /api/v1/agent/dispatch`	❌	❌	❌	❌	✅ (dashboard roles only)
Public checkout & confirm	`GET /api/v1/public/checkout/:sessionId`, `POST …/confirm`	—	—	—	—	Public (no credential)
Public payment-link spec	`GET /api/v1/public/payment-links/:slug/spec`	—	—	—	—	Public (no credential)
Public escrow	`/api/v1/public/escrow/*`	—	—	—	—	Public (no credential)
Billing events (internal)	`GET/POST /api/v1/billing/events`	`FACILITATOR_SECRET` only	—	—	—	—

Legend:

✅ = explicitly supported by the auth middleware. Secret (sk_), restricted (rk_), and publishable (pk_) keys all authenticate over the same Authorization: Bearer <key> header.
❌ = rejected.
— = not applicable.

Publishable keys are implicitly read-only: they authenticate client-safe endpoints (entitlement reads, events, coupon validation) but never authorize writes or money movement.

Dashboard-managed vs developer API

A clear boundary determines what you do through the dashboard versus what you build against with the SDKs and API keys:

Area	Where it’s done	Developer access
ℹ️ Catalog (plans, add-ons, credits, coupons, publish)	Dashboard Catalog screens	None — no SDK methods or API-key routes. Your app references plan IDs.
ℹ️ Environments (create, select, rename, delete)	Dashboard environment switcher	None — the SDKs auto-detect the environment from your key.
ℹ️ Invoice issuance (create, void, credit notes, refunds)	Dashboard Billing → Invoices	None — you receive `invoice.*` webhooks and offer customers the portal.
ℹ️ Webhook endpoints & secrets	Dashboard Settings → Webhooks	None — you build the receiving side (`verifyWebhookSignature`).
ℹ️ Audit log	Dashboard Billing → Audit Log	None — session-only, `audit:read` role.
ℹ️ Agent config, funding, dispatch	Dashboard Arcen Agent	None — agents use the `@arcenpay/agent` SDK.
ℹ️ Feature flag & rule definitions	Dashboard Features → Flags	None — you consume resolved flags via SDK hooks/methods.
✅ Customer records & payments	Node SDK (`ArcenClient`)	`identify`, companies CRUD (no delete), payment links, checkout sessions, activation, entitlements, usage, events.
✅ Embed & customer flows	React SDK (`@arcenpay/react`)	`ArcenPayProvider`, `ArcenEmbed` (checkout, portal, unsubscribe, resume), hooks.
✅ Autonomous agents	Agent SDK (`@arcenpay/agent`)	Payment links, escrow, mandates, balances, sessions.

Rule of thumb: if a capability appears as a screen in the dashboard (catalog, environments, invoices, webhooks, audit, agents, feature flags), it is managed there — not called from your backend. The SDKs and the node/React/agent endpoints above are the only surfaces your code should call.

Permission model

Restricted and secret keys can carry a permission list. Permissions are additive capabilities: a restricted key with tokens.create can only mint temporary access tokens, while a secret key with no explicit permissions has full access.

Permission	Grants access to
`entitlements.read`	`GET /api/v1/check`, `GET /api/v1/entitlements`
`usage.consume`	`POST /api/v1/usage/consume`
`customers.read`	Read-only company and event endpoints
`companies.write`	Create, update, and delete companies
`payments.write`	Payment-link and checkout-session writes
`subscriptions.write`	Subscription activation and lifecycle mutation
`tokens.create`	`POST /api/v1/api-keys/tokens` (mint `arc_tok_…`)

Publishable keys are implicitly read-only — they never carry permissions and never authorize writes.

Security invariants

Publishable keys never authorize money movement or private reads — endpoints opt in to publishable access via key-type allow-lists.
Keys are stored as SHA-256 hashes and shown exactly once at creation. If you lose the raw value, revoke the key and create a new one.
Restricted keys require at least one permission; secret keys with an empty permission list are full-access.
Keys can expire (expiresAt, 1–365 days) and can be revoked at any time; lastUsedAt is tracked for auditing and cleaning up stale credentials.
Embed access tokens are company-scoped and short-lived (60–900s, default 600s). They are minted only with a secret/restricted key that holds tokens.create, or with the Node SDK identify().

Generating credentials

All credentials are generated from the ArcenPay dashboard:

Open Settings

Go to Settings → API Keys.

Create a key

Click Create API Key, give it a name, choose the key type (Secret / Publishable / Restricted), pick permissions for secret/restricted keys, and set an optional expiry (1–365 days).

Copy the key now

The raw key is shown once — copy it to your secret manager immediately. It starts with the matching prefix (e.g. sk_test_…, pk_test_…, or rk_test_… in a development environment).

Set up webhook signing

Go to Settings → Webhooks, register your HTTPS endpoint, and copy the whsec_… signing secret (rotate anytime to invalidate the old one).

Using keys

Server-side (Node SDK)

The ArcenClient constructor accepts any supported key prefix:

export ARCENPAY_API_KEY=sk_live_...

import { ArcenClient } from "@arcenpay/node";

const arcen = new ArcenClient({ apiKey: process.env.ARCENPAY_API_KEY });

Browser (React SDK)

The React SDK is initialized with a publishable key — safe to ship to the browser:

export NEXT_PUBLIC_ARCENPAY_PUBLISHABLE_KEY=pk_live_...

import { ArcenPayProvider, useCompanyEntitlements } from "@arcenpay/react";

function App() {
  return (
    <ArcenPayProvider publishableKey={process.env.NEXT_PUBLIC_ARCENPAY_PUBLISHABLE_KEY}>
      <PlanCard />
    </ArcenPayProvider>
  );
}

function PlanCard() {
  const { entitlements } = useCompanyEntitlements({ companyKeys: { id: "cm_..." } });
  return <pre>{JSON.stringify(entitlements, null, 2)}</pre>;
}

Publishable-key reads require no session token — the backend resolves the company from the X-Arcen-Company-Keys header.

Company-keys headers

All client-safe endpoint calls that use a publishable key must identify the company (and optionally the user) using the X-Arcen-Company-Keys and X-Arcen-User-Keys headers. Each header is a comma-separated list of key=value pairs. At least one of id, wallet, or email is required for the company.

X-Arcen-Company-Keys: id=company_123,wallet=0xabc...
X-Arcen-User-Keys: id=user_123,wallet=0xabc...

id means your id, not ArcenPay’s. It is matched against the company’s externalId — the identifier from your own system that you supplied when the company was created. To be forgiving, an ArcenPay company id (the cm… value shown in the dashboard) is also accepted.What this means in practice: if you pass an id that matches neither, the company does not resolve. Company overrides and plan-derived rules are then evaluated as if no company were present, so the call returns a default-rule answer without raising an error. If a flag unexpectedly ignores an override you set, check that the identifier you are sending actually matches the company.When in doubt, wallet or email is the least ambiguous key to use.

The React SDK sends these headers automatically when you pass companyKeys to hooks like useCompanyEntitlements.

Keys in the SDK

import { ArcenClient } from "@arcenpay/node";

// Secret key — use on your backend only. Never ship it to a browser.
const arcen = new ArcenClient({ apiKey: process.env.ARCENPAY_API_KEY });

sk_… / rk_… keys authenticate all server-side REST endpoints (companies, events, payment links, checkout sessions, subscription activation, access-token minting). Publishable pk_… keys authenticate client-safe reads and customer identification only.

Temporary access tokens

Mint a short-lived, company-scoped token on your server, then hand it to the browser (e.g. for ArcenEmbed):

# Server-side only — authenticated with a secret/restricted key holding tokens.create
curl -X POST https://api.arcenpay.com/api/v1/api-keys/tokens \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "companyId": "cm_abc123", "ttlSeconds": 600 }'

{
  "data": { "token": "arc_tok_...", "companyId": "cm_abc123", "expiresAt": "2026-09-17T12:00:00.000Z" }
}

Dashboard sessions

The dashboard authenticates with a role-based session cookie (arcen_session). API requests from the dashboard carry this cookie and respect the signed-in user’s team role. You cannot create these cookies from a third-party integration — they are issued only by the ArcenPay dashboard auth flow.

Rate limits

API-key requests are rate-limited per key with a fixed window of 5,000 requests per 60 seconds. The limit is intentionally generous — it stops runaway loops and hostile bursts without shaping normal SDK, agent, or dashboard traffic. Exceeding it returns 429 with a retry hint. Anonymous requests with no key are additionally covered by bot and shield protection. See Rate limiting for details.

Common auth failures and fixes

Symptom	Cause	Fix
`401 Missing API key`	No `Authorization` header on a protected endpoint	Add `Authorization: Bearer <key>`
`401 Invalid or revoked API key`	Key rotated/revoked, or hash mismatch	Regenerate a key in the dashboard
`403 This endpoint cannot be called with publishable keys`	Using `pk_…` on a write endpoint	Server-side keys only (`sk_…`/`rk_…`)
`403 Missing permission(s): tokens.create`	Restricted key without the needed permission	Add the permission to the key, or use a full-access secret key
`401 Invalid or expired token`	An embed access token (`arc_tok_…`) was rejected	Regenerate the embed token; it expires in 60–900s
`401 Invalid API key`	The `sk_`/`pk_`/`rk_` key is not stored (revoked/rotated/never saved)	Regenerate a key in the dashboard and store the raw value once
`409 No workspace environment selected`	API-key call on an environment-scoped route without an environment	Use the dashboard or an API key bound to an environment
`429 Rate limit exceeded`	More than 5,000 API-key requests/60s	Back off and retry after the window resets

Never expose sk_… or rk_… keys in frontend code, client bundles, or public repositories. pk_… keys are specifically designed for the browser and grant read-only access only.

Credentials & environments — conceptual overview of the credential model
Sessions and access tokens — how embed tokens control ArcenEmbed
Error handling — auth error codes and troubleshooting

Get started

Credentials

Companies

Users

Events

Access control

Features

Subscriptions

Checkout sessions

Payment links

Invoices

Autonomous agents

Escrow

Mandates

Coupons

zkTLS proofs

Public specs

API keys and authentication

Base URL

The credentials that can authenticate a request

Key prefixes and environments

Which key works where — the endpoint auth matrix

Dashboard-managed vs developer API

Permission model

Security invariants

Generating credentials

Using keys

Server-side (Node SDK)

Browser (React SDK)

Company-keys headers

Keys in the SDK

Temporary access tokens

Dashboard sessions

Rate limits

Common auth failures and fixes

​Base URL

​The credentials that can authenticate a request

​Key prefixes and environments

​Which key works where — the endpoint auth matrix

​Dashboard-managed vs developer API

​Permission model

​Security invariants

​Generating credentials

​Using keys

​Server-side (Node SDK)

​Browser (React SDK)

​Company-keys headers

​Keys in the SDK

​Temporary access tokens

​Dashboard sessions

​Rate limits

​Common auth failures and fixes

​Related

Base URL

The credentials that can authenticate a request

Key prefixes and environments

Which key works where — the endpoint auth matrix

Dashboard-managed vs developer API

Permission model

Security invariants

Generating credentials

Using keys

Server-side (Node SDK)

Browser (React SDK)

Company-keys headers

Keys in the SDK

Temporary access tokens

Dashboard sessions

Rate limits

Common auth failures and fixes

Related