AI agents that act for users

// Stands in for your product's ticket table.
const tenantId = process.env.ACME_TENANT_ID;
export const tickets = new Map([
  ['T-1', { id: 'T-1', tenantId, title: 'Cannot export invoices', status: 'open' }],
  ['T-2', { id: 'T-2', tenantId, title: 'Duplicate of T-1', status: 'open' }],
]);

import { IamError } from 'better-iam';
import { sqliteAdapter } from 'better-iam/adapter-sqlite';
import { findDocument } from './documents.mjs'; // your document lookup from the Quickstart
import { tickets } from './tickets.mjs';

const ticketActions = ['tickets:read', 'tickets:update', 'tickets:delete'];

export default {
  database: sqliteAdapter({ filename: './iam.db' }),
  secret: process.env.BETTER_IAM_SECRET,
  baseURL: process.env.BETTER_IAM_BASE_URL,
  authentication: {
    // Prints delegation-request and delegation-confirmation emails. Development only.
    sendEmail: async (message) => {
      console.log(message.template, message.to, message.payload);
    },
  },
  permissions: {
    resourceTypes: {
      document: { actions: ['documents:read', 'documents:write'], attributes: { ownerId: 'string' } },
      ticket: { description: 'A support ticket', actions: ticketActions },
      'ticket-queue': { description: "An organization's ticket queue", actions: ticketActions },
    },
  },
  resolveResource: async ({ type, id }) => {
    if (type === 'ticket-queue') return { type, id, tenantId: id }; // a queue's ID is its organization's ID
    if (type === 'ticket') {
      const ticket = tickets.get(id);
      if (!ticket) throw new IamError('NOT_FOUND', 'Ticket not found', 404);
      return { type, id, tenantId: ticket.tenantId };
    }
    if (type === 'document') {
      const document = await findDocument(id);
      return { type, id, tenantId: document.tenantId, attributes: { ownerId: document.ownerId } };
    }
    throw new IamError('NOT_FOUND', 'Unknown resource type', 404);
  },
};

import { IamError } from 'better-iam';
import { iam } from '../iam';

const tenantId = process.env.ACME_TENANT_ID!;

async function signIn(email: string, password: string) {
  const result = await iam.api.auth.signIn({ tenantId, email, password });
  if ('mfaRequired' in result) throw new Error(`${email} must complete MFA (auth.verifyMfa)`);
  return result;
}

const ownerSignIn = await signIn(process.env.ACME_OWNER_EMAIL!, process.env.ACME_OWNER_PASSWORD!);
const owner = { token: ownerSignIn.token };
const aliceSignIn = await signIn(process.env.ALICE_EMAIL!, process.env.ALICE_PASSWORD!);
const alice = { token: aliceSignIn.token }; // a fresh sign-in: counts as a recent authentication
const aliceId = aliceSignIn.session.identityId;

const handler = await iam.api.roles.create(owner, {
  tenantId,
  name: 'Ticket handler',
  permissions: ['tickets:read', 'tickets:update', 'tickets:delete'],
});
await iam.api.bindings.create(owner, {
  tenantId,
  roleId: handler.id,
  subjectType: 'identity',
  subjectId: aliceId,
});

const agent = await iam.api.agents.create(owner, {
  tenantId,
  name: 'Support assistant',
  purpose: 'Triages and closes support tickets for the person it works for',
  model: 'claude-sonnet-5',
  provider: 'anthropic',
  protocols: ['mcp'],
  sponsorId: aliceId, // defaults to the caller when the caller is a person of the organization
  boundary: {
    version: 1,
    statements: [{ effect: 'allow', actions: ['tickets:*'], resources: ['ticket/*', 'ticket-queue/*'] }],
  },
  maxDelegatedSessionSeconds: 900, // 60 to 43200; 3600 by default
});

// The agent's own key: a biam_key_… bearer token. Its scopes also bound every delegated session it opens.
const { token: agentKeyToken } = await iam.api.credentials.create(owner, {
  tenantId,
  identityId: agent.id,
  name: 'production',
  scopes: ['tickets:read', 'tickets:update', 'tickets:delete'],
});
const agentKey = { token: agentKeyToken };
console.log('agent standing:', agent.standing); // ok

const assumed = await iam.api.delegations.assume(agentKey, {
  tenantId,
  delegationId: delegation.id,
  durationSeconds: 600, // at most the agent's and the delegation's caps; 900 or less by default
  sessionName: 'triage-run-1', // appears in decisions as principal.sessionName
});
const delegated = { token: assumed.token };
console.log(assumed.session.identityId === aliceId, assumed.session.agentId === agent.id); // true true

const check = (action: string, id: string) =>
  iam.authorize({ ...delegated, tenantId, action, resource: { type: 'ticket', id } });

console.log('close T-1:', (await check('tickets:update', 'T-1')).allowed); // true
console.log('delete T-2 before confirmation:', (await check('tickets:delete', 'T-2')).allowed); // false

import { iam } from '../iam';
import { tickets } from '../tickets.mjs';

export async function closeTicket(request: Request, ticketId: string): Promise<Response> {
  const ticket = tickets.get(ticketId);
  if (!ticket) return new Response('Not found', { status: 404 });
  // Throws ACCESS_DENIED (403) or UNAUTHENTICATED (401); the HTTP layer turns them into JSON errors.
  await iam.require({
    headers: request.headers,
    tenantId: ticket.tenantId,
    action: 'tickets:update',
    resource: { type: 'ticket', id: ticket.id },
  });
  const { identity, session } = await iam.authenticate({ headers: request.headers });
  // Better IAM audits refusals; record the allowed change, and which agent made it, in your own logs.
  console.log(`ticket ${ticket.id} closed for ${identity.id}`, session.agentId ? `by agent ${session.agentId}` : '');
  ticket.status = 'closed';
  return Response.json(ticket);
}

// The agent asks (it should read delegation.confirm first, with delegations.get):
const pending = await iam.api.delegations.requestConfirmation(delegated, {
  tenantId,
  action: 'tickets:delete',
  resource: { type: 'ticket', id: 'T-2' },
  reason: 'T-2 duplicates T-1, which I just closed',
  validSeconds: 120, // how long the approval stays usable: 30 to 3600; 300 by default
});

// Alice sees it in her inbox (or in the delegation-confirmation email) and approves:
const inbox = await iam.api.delegations.listConfirmations(alice, { tenantId, status: 'pending' });
await iam.api.delegations.decideConfirmation(alice, { tenantId, confirmationId: inbox[0]!.id, approve: true });

// The agent polls its request, then retries:
const decided = await iam.api.delegations.getConfirmation(delegated, { tenantId, confirmationId: pending.id });
console.log('confirmation:', decided.status); // approved
console.log('delete T-2 after approval:', (await check('tickets:delete', 'T-2')).allowed); // true
console.log('delete T-2 again:', (await check('tickets:delete', 'T-2')).allowed); // false: one approval, one call

import { iam } from '../iam';

export async function waitForConfirmation(
  delegated: { token: string },
  tenantId: string,
  confirmationId: string,
): Promise<boolean> {
  for (;;) {
    const request = await iam.api.delegations.getConfirmation(delegated, { tenantId, confirmationId });
    if (request.status === 'approved' && !request.expired) return true;
    if (request.status !== 'pending' || request.expired) return false; // rejected, used, or lapsed
    await new Promise((resolve) => setTimeout(resolve, 5_000));
  }
}

import { useConfirmations } from 'better-iam/react';

export function ConfirmationInbox({ tenantId }: { tenantId: string }) {
  const { pending, approve, reject } = useConfirmations({ tenantId });
  return (
    <ul>
      {pending.map((item) => (
        <li key={item.id}>
          {item.agent.name} wants to {item.action} on {item.resource.type}/{item.resource.id}: {item.reason}
          <button onClick={() => approve(item.id)}>Approve</button>
          <button onClick={() => reject(item.id)}>Reject</button>
        </li>
      ))}
    </ul>
  );
}

const trail = await iam.api.delegations.activity(alice, { tenantId, delegationId: delegation.id, limit: 20 });
for (const event of trail) console.log(event.action, event.outcome, event.resourceId);
// newest first: tickets:delete deny T-2 (the second delete), delegation:confirm, delegation:confirmation-request,
// tickets:delete deny T-2, delegation:assume, delegation:grant

// The sponsor's kill switch: no permission needed, effective at once.
await iam.api.agents.suspend(alice, { tenantId, agentId: agent.id, reason: 'Demo finished' });
try {
  await check('tickets:read', 'T-1');
} catch (error) {
  if (error instanceof IamError) console.log('after suspend:', error.code); // UNAUTHENTICATED
}

// Bring it back (a sponsor may resume only an agent they suspended), then end the delegation for good.
await iam.api.agents.resume(alice, { tenantId, agentId: agent.id });
await iam.api.delegations.revoke(alice, { tenantId, delegationId: delegation.id, reason: 'No longer on call' });