Skip to content
ActeraActera

Quickstart

This walkthrough uses the Actera TypeScript SDK to add runtime authorization before a server-side AI agent action. The integration handles every policy effect before the external side effect can run.

Install the SDK

Section titled “Install the SDK”

Install the TypeScript SDK in the service that dispatches agent actions:

Terminal window
pnpm add @actera/sdk

Configure the client

Section titled “Configure the client”

Set ACTERA_BASE_URL, ACTERA_ACCESS_TOKEN, and ACTERA_WORKSPACE_ID in your server environment. Retrieve accessible workspace UUIDs from GET /v1/workspaces; browser-facing slugs are navigation values and are not authoritative API scope.

import { ActeraClient } from '@actera/sdk'


const accessToken = process.env.ACTERA_ACCESS_TOKEN!


const actera = new ActeraClient({
  baseUrl: process.env.ACTERA_BASE_URL!,
  workspaceId: process.env.ACTERA_WORKSPACE_ID!,
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})

Keep the access token and client configuration on a trusted server. Browser-side checks can improve interface feedback, but they are not an authoritative enforcement boundary.

Authorize before acting

Section titled “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.

The agent, action, and context fields are described in Actions and context. For the REST request shape and retry behavior, see Evaluate an action and API conventions. A REQUIRE_APPROVAL result must follow the approval and continuation lifecycle.

Next steps

Section titled “Next steps”