Server-side access checks

The Node SDK provides authoritative access checks for your server. Unlike the React hooks which are for UI gating, these methods should guard any sensitive or billable operation on your backend. The ArcenClient automates authentication. Which key prefix you set depends on what the client needs to do:

Access checks (checkFlag, checkEntitlement, listEntitlements, consumeEntitlement) work with any key type (sk_, rk_, pk_).
Company/event/payment-link/checkout/session endpoints require a secret sk_… or restricted rk_… key. Publishable pk_… keys are read-only and rejected on writes.

For most backends, set ARCENPAY_API_KEY to a secret sk_… key so the whole client surface works:

ARCENPAY_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

The legacy api_… prefix has been removed from the platform. Regenerate any old keys as sk_…/rk_…/pk_….

See the endpoint auth matrix for the definitive key-per-endpoint guide.

checkFlag

Simple boolean check for a feature flag.

const enabled = await client.checkFlag("scan", { id: "company_123" });

if (!enabled) {
  throw new Error("This feature is not available on your plan");
}

Signature

client.checkFlag(featureKey: string, company: {
  id?: string;
  wallet?: string;
  email?: string;
}): Promise<boolean>

checkEntitlement

Full entitlement check including usage state and limits.

const entitlement = await client.checkEntitlement("scan", { id: "company_123" });

// {
//   key: "scan",
//   enabled: true,
//   reason: "PLAN_ALLOWS",
//   allocation: 500,
//   usage: 150,
//   exceeded: false
// }

if (!entitlement.enabled) {
  throw new Error("Upgrade required");
}

if (entitlement.exceeded) {
  throw new Error("Usage limit exceeded");
}

Signature

client.checkEntitlement(featureKey: string, company: {
  id?: string;
  wallet?: string;
  email?: string;
}): Promise<Entitlement>

Response fields

Field	Type	Description
`key`	`string`	The feature key that was checked.
`enabled`	`boolean`	Whether the company has access.
`reason`	`string`	Machine-readable resolution reason (e.g. `PLAN_ALLOWS`, `OVERRIDE`, `NO_PLAN`).
`allocation`	`number \| null`	Maximum units allocated in the current period. `null` = unlimited.
`usage`	`number`	Units consumed in the current period.
`exceeded`	`boolean`	Whether usage has reached or passed the allocation.

consumeEntitlement

Decrement a metered entitlement with idempotency protection.

const result = await client.consumeEntitlement({
  featureKey: "scan",
  company: { id: "company_123" },
  idempotencyKey: `scan-${requestId}`,
});

if (result.exceeded) {
  return new Response("Usage limit exceeded", { status: 402 });
}

// Continue with the billable operation...

Parameters

Param	Type	Required	Description
`featureKey`	`string`	Yes	The metered feature key.
`company`	`object`	Yes	Company identifier (id, wallet, or email).
`idempotencyKey`	`string`	Yes	Unique key per logical operation. Safe to retry.
`traits`	`object`	No	Attributes recorded with the consumption.

Always provide a unique idempotencyKey per logical operation. Reusing keys across different operations will cause incorrect consumption counts. Use keys like scan-{requestId} or export-{jobId}.

Server enforcement pattern

Combine entitlement checks with usage consumption for a complete server-side enforcement pattern:

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

const client = new ArcenClient({
  apiKey: process.env.ARCENPAY_API_KEY!,
});

export async function handleScan(companyId: string, fileId: string) {
  // 1. Check if the company has access at all
  const entitlement = await client.checkEntitlement("scan", { id: companyId });
  if (!entitlement.enabled) {
    return Response.json(
      { error: "Scans are not available on your plan. Upgrade to continue." },
      { status: 402 }
    );
  }

  // 2. Consume the entitlement before performing the operation
  const result = await client.consumeEntitlement({
    featureKey: "scan",
    company: { id: companyId },
    idempotencyKey: `scan-${fileId}`,
  });

  if (result.exceeded) {
    return Response.json(
      { error: `Limit reached (${result.usage}/${result.allocation}). Upgrade to continue.` },
      { status: 402 }
    );
  }

  // 3. Perform the actual operation
  const scanResult = await performScan(fileId);

  return Response.json({ data: scanResult });
}

Error handling

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

try {
  await client.checkEntitlement("scan", { id: "company_123" });
} catch (error) {
  if (error instanceof ArcenApiError) {
    if (error.statusCode === 404) {
      // Feature key doesn't exist
    } else if (error.statusCode === 401) {
      // Invalid API key
    } else if (error.statusCode === 403) {
      // Workspace doesn't have access to feature flags
    }
  }
}

ArcenClient reference — all client methods
Webhooks reference — verify webhook signatures
Entitlements concept — how entitlements resolve

React SDK

Node.js SDK

Agent SDK

Server-side access checks

checkFlag

Signature

checkEntitlement

Signature

Response fields

consumeEntitlement

Parameters

Server enforcement pattern

Error handling

​checkFlag

​Signature

​checkEntitlement

​Signature

​Response fields

​consumeEntitlement

​Parameters

​Server enforcement pattern

​Error handling

​Related

checkFlag

Signature

checkEntitlement

Signature

Response fields

consumeEntitlement

Parameters

Server enforcement pattern

Error handling

Related