Build a multi-user Claude Agent SDK app that acts as each of your users

A multi-user agent fails in a way no demo will show you. You put one Jira token in .env, wire it into a Claude Agent SDK tool, and the agent works, for you. Then the second user runs it, and it reads your issues, your pipeline, your Slack. Nothing throws, the run is green, and the audit trail says one service account did all of it.

This is not a hypothetical, and it is not a skill issue. GitGuardian's 2026 secrets report counted 24,008 unique secrets sitting in MCP-related config files on public GitHub, 2,117 of them live, and traced the pattern to tutorials that tell developers to put credentials in config. The Agent SDK's own documentation is part of that pattern: the custom tools page never mentions identity, multi-tenancy, or request scoping, and the MCP page demonstrates Authorization: Bearer ${process.env.API_TOKEN} before dismissing OAuth in a single sentence. Per-user credential vaults do exist in Anthropic's Managed Agents, but they inject into remote MCP servers and do nothing for the in-process tools you define with createSdkMcpServer.

So if you are building in-process tools for more than one person, the identity plumbing is yours to write. This post is about where it goes.

Where the identity has to live

Prompting will not fix this, because the problem sits below the model. There is exactly one design rule that matters, and it is structural rather than behavioral:

The acting user is a closure variable, never a tool parameter.

Build the tool surface per request, capture the user once when you build it, and expose no field in any input schema through which the model could name a different user. A prompt-injected model can then emit anything it likes and still cannot change whose access a call runs with, because there is nowhere to put the lie. Compare that to a userId argument on a tool, validated in the handler: now every handler is a place where the check can be forgotten, and the model is holding a knob it should never have been offered.

Everything else in this post is a consequence of that one rule.

What you will build

Five files, in this order. Each one is short, and the whole thing runs behind a single Next.js route.

1. app/api/agent/route.ts, to resolve who is asking from the AuthKit session
2. lib/relay.ts, to call a provider as that user without holding their token
3. lib/agent-tools.ts, to build the tool surface per request with the user closed over
4. lib/agent.ts, to take away every tool the agent has no business holding
5. lib/audit.ts, to record what happened under the person's name

Step 1: Resolve the acting user server-side

withAuth() from @workos-inc/authkit-nextjs reads the user out of the AuthKit session. The return type is a discriminated union, UserInfo | NoUserInfo: signed out, you get { user: null } and nothing else, so accessToken and the rest are absent too. Passing ensureSignedIn: true redirects to sign-in instead of returning null. Session management comes from the AuthKit proxy, authkitProxy in proxy.ts on Next.js 16+ or authkitMiddleware in middleware.ts on 15 and earlier, and the library installs alongside the WorkOS Node SDK, which is a peer dependency. Note that withAuth() reads request headers the proxy sets, so it only works with the proxy active.

organizationId comes from the same call, but it is optional: it is populated from the org_id access token claim, so a session that was not authenticated under an organization simply does not have one. That matters more than it looks, because audit log events are organization-scoped. An agent run with no organization is a run you cannot write an audit trail for, so fail it closed rather than discovering the gap later in your logs:

  
// app/api/agent/route.ts
import { withAuth } from '@workos-inc/authkit-nextjs';
import { runAgent } from '@/lib/agent';

export async function POST(request: Request) {
  const { user, organizationId } = await withAuth({ ensureSignedIn: true });

  // Audit events are organization-scoped. No organization, no trail, no run.
  if (!organizationId) {
    return Response.json(
      { error: 'This agent requires an organization-scoped session.' },
      { status: 403 },
    );
  }

  const { prompt } = await request.json();
  const { result } = await runAgent({
    actingUser: { userId: user.id, organizationId },
    runId: crypto.randomUUID(),
    prompt,
  });

  return Response.json({ result });
}
  

user.id comes from the encrypted session cookie. It does not come from the request body, a query string, or anything the model produced earlier in the loop. That is the whole tenant boundary, so it is worth being boring about.

Step 2: Call the provider without holding the token

Each user's provider grant lives in their Pipes connected account, which handles the OAuth flow, credential storage, and refresh. Scopes are configured per provider integration rather than per request and are granted when the user connects, which makes that dashboard field the outer wall of everything the agent can ever do.

Pipes offers two ways to use that grant. The credential-vending endpoint hands your code the user's token; relay has WorkOS make the call and return the provider's response, so the token never enters your environment. The docs put it plainly: access tokens for trusted infrastructure and long-running syncs, relay for agents, sandboxes, and untrusted runtimes. An agent runtime reads untrusted text for a living, so relay it is.

I have written up relay's request and error surface in detail already, so here is only what you need to build the tool layer. Delegated access for AI agents covers why an agent should not hold the token at all, 402, not 401 covers the authorization-required response, and the no-session tutorial covers the full header and error inventory for a scheduled worker.

The short version: send your request to https://api.workos.com/relay with your WorkOS API key in Authorization, the target URL in X-Relay-URL, and the user in X-Relay-User. Relay accepts any HTTP method and passes it through. Add X-Relay-Organization when the connection is organization-scoped, and omit it when it is not. Every proxied response carries X-Relay-Upstream-Status, so its presence tells you the provider answered and its absence tells you relay did.

  
// lib/relay.ts
export type ActingUser = { userId: string; organizationId: string };

export class ReconnectRequired extends Error {
  constructor(
    readonly provider: string,
    readonly authorizationUrl: string | null,
  ) {
    super(`Reconnect ${provider}`);
  }
}

export async function relayFetch(
  user: ActingUser,
  targetUrl: string,
  init: { method?: string; body?: string; headers?: Record<string, string> } = {},
): Promise<Response> {
  const response = await fetch('https://api.workos.com/relay', {
    method: init.method ?? 'GET',
    body: init.body,
    headers: {
      ...init.headers,
      // The WorkOS API key, injected at request time. Never a provider token.
      Authorization: `Bearer ${process.env.WORKOS_API_KEY}`,
      'X-Relay-URL': targetUrl,
      'X-Relay-User': user.userId,
      'X-Relay-Organization': user.organizationId,
    },
  });

  // An upstream status means the provider answered. Without it, relay itself did.
  if (response.headers.get('X-Relay-Upstream-Status')) return response;

  const error = (await response.clone().json().catch(() => ({}))) as Record<string, string>;

  if (error.code === 'relay_authorization_required') {
    throw new ReconnectRequired(error.connection, error.authorization_url ?? null);
  }
  if (response.status === 404 && !error.code) {
    throw new Error('Pipes relay is not enabled for this WorkOS environment.');
  }
  return response;
}
  

Three notes for production. A user who never connected, whose grant was revoked, or whose token can no longer be refreshed gets a 402 with relay_authorization_required, deliberately not a 401 or 403 so you cannot confuse it with a WorkOS auth failure or a passthrough. Treat authorization_url as optional: it is null for API key and client-credentials connections, and also null when a provider's OAuth configuration is incomplete. And split the rest of the error surface rather than collapsing it as this helper does, because the codes mean different things: relay_upstream_error (502) is worth a retry, relay_credential_error (502) is not, and relay_credential_invalid (400) is a different problem again.

Relay is in early access. Contact WorkOS support by email or Slack to enable it for your environment.

Step 3: Mint the tool surface per request

A custom tool in the Agent SDK is a name, a description, a Zod raw shape that types the handler's args, and an async handler. createSdkMcpServer wraps them into a server that runs in-process rather than as a subprocess, and the key you give it in mcpServers becomes the {server_name} segment of each fully qualified tool name, mcp__{server_name}__{tool_name}. Note that it is the mcpServers key that is used, not the server's own name field.

Build that server per request, with the acting user closed over:

  
// lib/agent-tools.ts
import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
import { z } from 'zod';
import { relayFetch, ReconnectRequired, type ActingUser } from './relay';
import { recordAgentAction } from './audit';

const say = (value: unknown) => ({
  content: [
    { type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value) },
  ],
});

const failed = (message: string) => ({
  content: [{ type: 'text' as const, text: message }],
  isError: true,
});

async function guarded(
  user: ActingUser,
  runId: string,
  action: string,
  target: { id: string; type: string },
  call: () => Promise<Response>,
  // Some providers answer 200 with a failure in the body. See the Slack tool.
  validate?: (body: unknown) => string | null,
) {
  try {
    const response = await call();
    if (!response.ok) {
      return failed(`${action} failed upstream with ${response.status}. Skip it and say so.`);
    }

    const body = await response.json();
    const rejection = validate?.(body);
    if (rejection) {
      return failed(`${action} was rejected by the provider: ${rejection}. Skip it and say so.`);
    }

    // Only after the call actually succeeded. An audit trail of attempts is worse
    // than no audit trail, because it reads like a record of completed work.
    await recordAgentAction({ user, runId, action, target });
    return say(body);
  } catch (error) {
    if (error instanceof ReconnectRequired) {
      return failed(`This user has not connected ${error.provider}. Ask them to reconnect.`);
    }
    throw error;
  }
}

export function buildActingUserServer(user: ActingUser, runId: string) {
  // `user` is captured once, here, for this request. No tool takes a user
  // argument, so nothing the model emits can change whose access a call runs with.

  let cloudId: Promise<string> | undefined;
  const jiraCloudId = () => {
    cloudId ??= relayFetch(user, 'https://api.atlassian.com/oauth/token/accessible-resources')
      .then((response) => response.json())
      .then((sites: Array<{ id: string }>) => sites[0].id);
    return cloudId;
  };

  const searchIssues = tool(
    'search_issues',
    "Search the user's Jira issues with a JQL query.",
    {
      jql: z.string().describe('JQL, e.g. assignee = currentUser() AND status != Done'),
      maxResults: z.number().int().min(1).max(50).default(20),
    },
    async (args) => {
      const site = await jiraCloudId();
      const params = new URLSearchParams({
        jql: args.jql,
        maxResults: String(args.maxResults),
        fields: 'summary,status,assignee,duedate',
      });
      return guarded(user, runId, 'agent.jira_searched', { id: site, type: 'jira_site' }, () =>
        relayFetch(
          user,
          `https://api.atlassian.com/ex/jira/${site}/rest/api/3/search/jql?${params}`,
        ),
      );
    },
    { annotations: { readOnlyHint: true } },
  );

  const searchDeals = tool(
    'search_deals',
    "Search the user's HubSpot deals.",
    {
      query: z.string().describe('Free-text search across the default deal properties'),
      limit: z.number().int().min(1).max(200).default(20),
    },
    async (args) =>
      guarded(user, runId, 'agent.crm_searched', { id: 'deals', type: 'hubspot_object' }, () =>
        relayFetch(user, 'https://api.hubapi.com/crm/objects/2026-03/deals/search', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ query: args.query, limit: args.limit }),
        }),
      ),
    { annotations: { readOnlyHint: true } },
  );

  const postSummary = tool(
    'post_summary',
    'Post one message to a Slack channel as the user.',
    { channel: z.string().describe('Slack channel ID'), text: z.string().max(4000) },
    async (args) =>
      guarded(
        user,
        runId,
        'agent.slack_message_posted',
        { id: args.channel, type: 'slack_channel' },
        () =>
          relayFetch(user, 'https://slack.com/api/chat.postMessage', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ channel: args.channel, text: args.text }),
          }),
        // Slack returns HTTP 200 with {"ok": false} for application errors.
        (body) => {
          const slack = body as { ok?: boolean; error?: string };
          return slack.ok ? null : (slack.error ?? 'unknown Slack error');
        },
      ),
  );

  return createSdkMcpServer({
    name: 'acting_user',
    version: '1.0.0',
    tools: [searchIssues, searchDeals, postSummary],
  });
}
  

That Slack validator is not defensive boilerplate. Slack answers missing_scope, not_in_channel, and invalid_auth with HTTP 200 and {"ok": false, "error": "..."}, so a handler that checks only response.ok tells the model the message posted, returns a green run, and writes an audit event for a Slack post that never happened. That is the exact failure this post opens with, reproduced by the framework rather than by a shared token. Check the body.

Three provider details worth their lines. Jira OAuth 2.0 (3LO) calls go through api.atlassian.com rather than your-domain.atlassian.net, using /ex/jira/{cloudid}/{api}, and you get the cloudid from /oauth/token/accessible-resources on that same host. The search endpoint is /rest/api/3/search/jql; the older /rest/api/3/search was fully retired in October 2025 and now returns 410, so treat any snippet using it as dead code. Pagination on the new endpoint uses nextPageToken rather than startAt, there is no total, and page size is advisory, so follow the token rather than trusting maxResults. HubSpot's search is a POST to the date-versioned object path, currently /crm/objects/2026-03/deals/search, capped at 200 results per page, returning dealname, amount, closedate, pipeline, and dealstage among its defaults.

readOnlyHint: true on the two read tools lets the runtime call them in parallel with other read-only tools, and it defaults to false. Returning isError: true lets you compose the message the model reads rather than surfacing a raw exception, so one user's revoked Slack grant degrades a run instead of ending it.

‍

Step 4: Take away the tools it should not have

Scoping an agent to least privilege is not one setting. It is four, and they fail differently.

• ‍The grant. Whatever scopes the provider integration requests at connect time is the ceiling. A read-only agent asking for write scopes has already lost the argument.‍
• The route. Relay only reaches a supported provider's allowlisted hosts, only over HTTPS, and it does not follow redirects. A confused tool cannot be talked into calling an arbitrary endpoint with someone's credential attached. Check the allowlist when you write a tool: jira resolves to api.atlassian.com and hubspot to api.hubapi.com, but slack is slack.com only. api.slack.com is not allowlisted and returns 400 relay_invalid_url.‍
• Availability. Passing tools: [] in the query options removes every built-in, leaving only your MCP tools. An agent that reads Jira has no business holding Bash.‍
• Permission. Tools named in allowedTools run without a prompt. For a headless agent, pair the allowlist with permissionMode: 'dontAsk', which denies anything unlisted outright instead of prompting a human who is not there.

  
// lib/agent.ts
import { query } from '@anthropic-ai/claude-agent-sdk';
import { buildActingUserServer } from './agent-tools';
import type { ActingUser } from './relay';

export async function runAgent(opts: {
  actingUser: ActingUser;
  runId: string;
  prompt: string;
}) {
  const server = buildActingUserServer(opts.actingUser, opts.runId);

  for await (const message of query({
    prompt: opts.prompt,
    options: {
      mcpServers: { acting_user: server },
      tools: [], // Remove every built-in: Read, Write, Bash, WebFetch.
      allowedTools: [
        'mcp__acting_user__search_issues',
        'mcp__acting_user__search_deals',
        'mcp__acting_user__post_summary',
      ],
      permissionMode: 'dontAsk', // Anything unlisted is denied, not prompted.
    },
  })) {
    if (message.type === 'result' && message.subtype === 'success') {
      return { result: message.result };
    }
  }

  return { result: null };
}
  

Two things about that config are easy to get wrong. allowedTools stops mattering the moment you set permissionMode: 'bypassPermissions', which approves every tool including Bash, Write, and Edit no matter what your allowlist says. And a call auto-approved by an allow rule skips your canUseTool callback entirely, so a policy check placed there is silently bypassed for exactly the tools you pre-approved. If you need a check to run on every call, use a PreToolUse hook: hooks run first in the permission evaluation, and a hook deny holds even under bypassPermissions.

Pin your SDK version and test the availability layer rather than trusting a blog post about it, including this one. The distinction between which options remove a tool from Claude's context and which options merely gate approval has moved between versions, and it is load-bearing for the argument above. tools: [] removing built-ins is stable; the rest deserves a test in your own repo.

The fifth wall is not yours at all. Because each call carries the user's own credential, the provider enforces its own model on top of everything above. Atlassian is explicit about it: "the permissions held by the user an app is acting for always constrain the app, regardless of the app's scopes."

Step 5: Audit the person, not the service account

An agent that acts as fifteen people needs an answer to "who did this," and the answer should not be the name of your service account. WorkOS Audit Log events give you an actor and a target shape you control, which is more work than reading a claim out of a token response and worth it.

  
// lib/audit.ts
import { WorkOS } from '@workos-inc/node';
import type { ActingUser } from './relay';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

export async function recordAgentAction(opts: {
  user: ActingUser;
  runId: string;
  action: string;
  target: { id: string; type: string };
}) {
  await workos.auditLogs.createEvent(
    opts.user.organizationId,
    {
      action: opts.action,
      occurredAt: new Date(),
      actor: { id: opts.user.userId, type: 'user' },
      targets: [opts.target, { id: opts.runId, type: 'agent_run' }],
      context: { location: process.env.APP_EGRESS_IP! },
      metadata: { run_id: opts.runId, agent: 'workspace_assistant' },
    },
    // Key on run, action, and target so a retried tool call does not double-log,
    // while two legitimate Slack posts in the same run both land.
    { idempotencyKey: `${opts.runId}:${opts.action}:${opts.target.id}` },
  );
}
  

Configure the allowed event schemas before emitting anything, either in the dashboard or with createSchema(), or the call fails. The actor here is the person rather than the agent, because that is the question an auditor asks first, and the run ID rides along as both a target and a metadata field so one session can be reconstructed from the trail.

Pass the idempotency key explicitly. The raw API will derive one from the event content if you omit it, but @workos-inc/node fills the gap first with workos-node-${randomUUID()}, so a keyless retry with an identical payload creates a duplicate event. Two more limits worth knowing before you design your event shape: context.location is required, metadata takes at most 50 keys with values up to 500 characters and no nesting, and retention is 30 days by default, raisable to 365 per organization through the retention API. Actor and target objects also accept name and their own metadata, which is usually a better place for a human-readable label than the event metadata.

Optional: Give admins something to turn off

Per-user grants solve the wrong problem for an IT admin, who wants a lever over the whole company. Organization-scoped providers in Pipes let one organization override three things: whether a provider is enabled, the scopes it requests, and the OAuth credentials it uses. That is the difference between "our users can connect Jira" and "our users connect Jira through our OAuth app, read-only, and HubSpot is off."

Admins configure it through the drop-in Pipes Admin widget, gated by the widgets:pipes:manage permission, or through the management API:

  
const configuration = await workos.pipes.configureOrganizationProvider({
  organizationId: 'org_01EHZNVPK3SFK441A1RGBFSHRT',
  provider: 'github',
  enabled: true,
  scopes: ['repo', 'user:email'],
  clientId: 'Iv1.a1b2c3d4e5f6g7h8',
  clientSecret: 'example_client_secret_value',
});
  

One line for the onboarding runbook: for a provider set to use organization credentials, that organization's users cannot connect until the admin supplies a client ID and secret.

What this design does not fix

• ‍Identity binding stops impersonation, not misuse. Scopes are granted at connect time, not per task, so an agent that gets confused still operates at the full width of what the user authorized. Narrow the integration's scopes rather than trusting the loop to behave. This is the objection to pre-empt if you post this design anywhere developers are reading: the credential half is close to a solved problem, and the unsolved half is enforcement between the agent's decision and the action firing.‍
• The WorkOS API key stays in the runtime. Relay removes provider tokens from the calling environment, not that key, which authenticates every WorkOS call for the environment. Inject it at request time rather than baking it into agent-visible code or prompts.‍
• Relay is a proxy with limits. Bodies are forwarded byte-for-byte up to 5 MB and the upstream timeout is 30 seconds, which is fine for tool calls and wrong for a bulk export. That is what the credential-vending path and a trusted worker are for. Note also that "returned verbatim" is true of status and body but not of every header: hop-by-hop headers and Set-Cookie are stripped.‍
• Revocation is fast on your side and slower on the provider's. deleteUserConnectedAccount({ userId, slug }) removes the stored access and refresh tokens and returns 204, after which the next relayed call comes back 402. It does not revoke access at the provider, and the user may still need to disconnect your app there. Note the parameter is slug, not provider, which differs from configureOrganizationProvider.‍
• The cloudId shortcut is wrong for multi-site customers. jiraCloudId() takes the first site in the response. Atlassian also warns that the id is not unique across container types, and the endpoint tells you nothing about the user's permissions within a site, so pin the site explicitly once you have a customer with two.

The test that matters is not the happy path. Sign in as a second user, run the same prompt, and check that the run touched nothing belonging to the first. Then read the audit log and check that it names a person rather than a robot.

Prove it with a second user

The happy path proves nothing here, because the failure this post is about does not throw. Every check below is one that a green run can still fail:

• Sign in as a second user and run the same prompt. Confirm the run touched nothing belonging to the first. This is the whole test; the rest are details of it.
• Revoke one user's Slack grant mid-session. The run should degrade to a reconnect message and keep going, not die on a stack trace and not silently skip the step.
• Post to a channel the user is not a member of. The tool must report failure. Slack answers 200, so this is the check that proves your body validation is wired up rather than just written.
• Read the audit log. It should name a person, a target, and a run ID you can reconstruct a session from, not a service account.
• Try a session with no organization. The request should be refused, because an unaudited agent run is not a feature.

Do all five as a different user than the one who built it. The bug in a multi-user agent is almost never in the code path you wrote; it is in the assumption that there is only one of you.

The agent will still get things wrong. The difference is that when it does, the damage is bounded by one person's grant, and the audit log says whose. That is the whole return on the closure variable at the top of this post.

If the other half of your workload has no signed-in user at all, a nightly job or a queue consumer, the same relay call works with a stored grant and no session. That is the companion tutorial.

Build this on WorkOS

Four pieces do the work in this post.

• ‍AuthKit resolves who is asking.
• ‍Pipes holds each user's grant and refreshes it.
• ‍Relay makes the call without handing your runtime the token.
• ‍Audit Logs records who did what, under their own name.

AuthKit, Pipes, and Audit Logs are self-serve. Relay is in early access, so email or Slack support to have it turned on for your environment before you start wiring tools against it.

AuthKit is free up to 1 million monthly active users, which is more headroom than you need to build this and prove it with a second user. Create a WorkOS account, connect your first provider, and give your agent an identity that is not yours.