Quickstart

This walkthrough adds an authorization check before a server-side action and handles every possible policy effect.

Install the SDK

npm install @actera/sdk

With pnpm or Yarn:

pnpm add @actera/sdk
yarn add @actera/sdk

Configure the client

Set ACTERA_BASE_URL and ACTERA_WORKSPACE_SLUG in your server environment. Supply the authentication headers issued for your environment through your application’s secret configuration.

import { ActeraClient } from '@actera/sdk'

const actera = new ActeraClient({
  baseUrl: process.env.ACTERA_BASE_URL!,
  workspaceSlug: process.env.ACTERA_WORKSPACE_SLUG!,
  headers: loadActeraAuthenticationHeaders(),
})

Keep connection configuration and authentication material on the server. Browser-side checks are useful for interface feedback, but they are not an enforcement boundary.

Authorize before acting

const decision = await actera.authorizeAction({
  agent: { id: 'refund-agent' },
  action: {
    type: 'refund.create',
    attributes: { amount: 80, currency: 'GBP', customer_id: 'cus_123' },
  },
  context: { customer: { previous_refunds: 0, fraud_flagged: false } },
  idempotencyKey: request.id,
})

switch (decision.effect) {
  case 'ALLOW':
    return issueRefund(request)
  case 'REQUIRE_APPROVAL':
    return queueForApproval(decision.id)
  case 'BLOCK':
    throw new Error(`Action blocked: ${decision.explanation}`)
}

Use one stable idempotency key for one logical action. A retry with the same key returns the existing decision instead of creating another one. Do not reuse a key for different input.

Next steps