Agent Identity
I spent three days debugging a problem that had nothing to do with my code. I was building an MCP server for a CRM integration. The LLM called my tools correctly, my backend returned the right data, and everything worked in testing.
Then I deployed it for a team, and every user saw every other user’s data.
The LLM was forwarding a shared API key. My backend had no idea who was asking. All it saw was a service credential that said “this request came from ChatGPT,” with nothing about which person in ChatGPT triggered it.
That is the agent identity problem, and it is the first thing an Agentic Control Plane solves.
Related reading: What is an Agentic Control Plane? · What is an Agent Delegation Chain? · What is an MCP Control Plane? · Agent identity vs. agent control (Okta, Auth0)
Why identity comes first
Without verified identity, the rest of the control plane has nothing to work with:
- Policies: you can’t enforce them if you don’t know who is asking.
- Cost: you can’t attribute spend to someone you can’t name.
- Audit: you can’t record who took an action.
- Permissions: you can’t scope them if every request looks the same.
- Anomalies: you can’t spot them without a baseline per user.
Policy enforcement, rate limiting, PII detection and audit logging all depend on knowing who is making the request.
Most AI systems treat identity as an afterthought. API keys get shared and service accounts get reused. The LLM sits in the middle holding one credential on each side.
In ACP, every request carries an identity. For a human using ChatGPT or Claude, that is a verified JWT from your identity provider. For an agent built in the console or called through the API, it is the agent or the key that made the call. That identity follows the request through the whole control pipeline.
The four paths to identity
An agent gets its identity in one of four ways, depending on how it was created and who is using it.
1. User-bound sessions (JWT from your IdP)
This is the most common path for enterprise MCP deployments. A person signs in with your identity provider (Auth0, Okta, Entra ID, Firebase, Keycloak, or any OIDC provider) and receives an RS256-signed JWT. When they use an AI client such as ChatGPT, Claude or Cursor, that JWT is forwarded to the control plane.
The control plane verifies the JWT, reads the user’s identity from it, and attaches it to every downstream request. Your backend receives x-user-uid on every call. That is a verified user ID, not a shared API key.
Coding-agent hooks (Claude Code, Cursor and the others) work differently. They authenticate to ACP with a workspace API key (gsk_...) instead of an IdP login, so the JWT flow below applies to MCP and gateway traffic, not to those hooks.
2. Console-created agents
In ACP Cloud you can create agents from the dashboard. Each gets an agent ID bound to the creating user and workspace. You set permissions visually: which tools the agent can use, which scopes it runs under, and its budget.
When a console-created agent runs on its own (on a schedule, from a webhook, or called by another agent), it carries its creator’s identity context. The audit trail records both the agent and the human who created it, so someone is always accountable.
3. API-created agents
You can also create agents through the REST API. API keys look like gsk_{slug}_{random}. The slug identifies the workspace, so no tenant parameter is needed.
POST /api/v1/agents
Authorization: Bearer gsk_acmecorp_k8f7a2b1c9d4e5f6
Content-Type: application/json
{
"name": "Daily report generator",
"model": "gpt-4o",
"systemPrompt": "Generate a daily sales summary from CRM data.",
"enabledTools": ["salesforce.query", "salesforce.getRecord"],
"scopes": ["salesforce.*"],
"maxBudgetCents": 500,
"maxToolCalls": 50,
"delegatable": true,
"canDelegate": false
}
The API supports full CRUD (GET, POST, PUT, DELETE) plus invocation (POST /api/v1/agents/:id/run). The creating principal is recorded on the agent profile (createdBy: "apikey:{keyId}"). The agent inherits workspace policies and can only use the scopes and tools it was granted when created.
When an API-created agent runs, the audit trail attributes every action to the key that triggered it. You always know which integration or automation started the chain.
4. External agents (A2A protocol)
Agents from other systems discover your ACP workspace through well-known endpoints and present credentials. ACP verifies them before granting access to tools or other agents. This is how agent-to-agent calls work across organizations. More on agent-to-agent governance →
What happens on a tool call
Here is what happens when a user triggers a tool call through an MCP client with an IdP login.
Steps 5 to 7 are where the policy decision happens. The control plane:
- Takes the Bearer token from the
Authorizationheader. - Fetches your IdP’s public keys from the JWKS endpoint. These are cached after the first fetch.
- Verifies the RS256 signature. There are no shared secrets and no trust-on-first-use.
- Checks the standard claims:
exp(not expired),aud(correct audience),iss(correct issuer). - Builds the identity from
sub, scopes, roles, tenant ID and email, as a normalizedGatewayIdentityobject. - Runs the control pipeline: scope enforcement, ABAC policies, rate limits, PII detection.
- Logs the action with the identity attached.
Only then does the request reach your backend, with verified identity headers added. Once your IdP’s keys are cached, verification is local and typically takes single-digit milliseconds. The first request after startup or a key rotation is slower because it fetches the keys.
What’s in the JWT
When a user signs in with your identity provider, they receive an RS256-signed JWT. Decoded, it looks like this:
{
"header": {
"alg": "RS256",
"typ": "JWT",
"kid": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMD..."
},
"payload": {
"sub": "auth0|8f3a2b1c9d4e5f6a",
"aud": "https://api.yourapp.com",
"iss": "https://yourcompany.auth0.com/",
"scope": "tool:crm:read tool:jira:write",
"org_id": "org_acme_corp",
"permissions": ["salesforce.query", "github.listRepos"],
"exp": 1739145600,
"iat": 1739142000
}
}
Each claim has a job in the control pipeline.
subis the user’s unique ID. It becomesx-user-uidon downstream requests. It is not an API key and not an email. It is a verified user ID that can’t be forged.audis the intended audience. The control plane rejects tokens meant for a different service. A token issued for your staging environment won’t work in production, even with a valid signature.issis the issuer. ACP checks it matches your configured IdP, then fetches that issuer’s public keys from its JWKS endpoint.scopeis what the user may do.tool:crm:readallows reads from the CRM connector.tool:jira:writeallows creating Jira tickets. No scope, no access.org_idisolates tenants. Users in one organization can’t reach another organization’s data.kidis the ID of the key that signed the token. ACP fetches the matching public key from your IdP and checks the signature locally. No shared secrets leave your IdP.
The verification code
This is the implementation in identifiabl-core, the open-source module that verifies JWTs. It is simplified here for reading.
import { createRemoteJWKSet, jwtVerify } from "jose";
export function createIdentifiablVerifier(config: IdentifiablCoreConfig) {
const issuerNoSlash = trimTrailingSlashes(config.issuer);
const jwksUri = config.jwksUri
|| `${issuerNoSlash}/.well-known/jwks.json`;
// JWKS keys are cached in memory, re-fetched only on key rotation
const JWKS = createRemoteJWKSet(new URL(jwksUri));
return async (token: string): Promise<VerifyResult> => {
try {
const { payload } = await jwtVerify(token, JWKS, {
audience: config.audience,
algorithms: ["RS256"], // No HS256, asymmetric only
clockTolerance: "60s", // Allow 60s clock skew
});
// Double-check issuer (normalized, handles trailing slashes)
const iss = trimTrailingSlashes(String(payload.iss || ""));
if (iss !== issuerNoSlash) {
return { ok: false, error: "invalid_token",
detail: `unexpected "iss" claim value: ${payload.iss}` };
}
// Map JWT claims → GatewayIdentity
const identity = mapPayloadToGatewayIdentity(payload, config);
return { ok: true, identity, payload };
} catch (e: any) {
return { ok: false, error: "invalid_token", detail: e?.message };
}
};
}
Four design choices to know about.
RS256 only. The verifier rejects HS256 tokens. That blocks a known attack where someone uses a public key as an HMAC secret to forge tokens. With asymmetric signatures, the private key never leaves your IdP.
JWKS caching. The createRemoteJWKSet function from the jose library keeps public keys in memory. The first request fetches your IdP’s JWKS endpoint, and later requests use the cache. If a token arrives with an unknown kid because your IdP rotated keys, it fetches again.
Issuer normalization. Auth0 tokens include iss: "https://tenant.auth0.com/" with a trailing slash. Okta tokens don’t. The verifier strips the slash on both sides before comparing.
Clock tolerance. A 60-second tolerance covers small clock differences between your IdP and the control plane. Without it, tokens would sometimes be rejected as expired, an intermittent failure that is hard to trace.
The GatewayIdentity object
After verification, the JWT is mapped into a normalized GatewayIdentity that flows through the pipeline.
interface GatewayIdentity {
sub: string; // "auth0|8f3a2b1c9d4e5f6a"
issuer: string; // "https://yourcompany.auth0.com"
tenantId?: string; // "org_acme_corp"
email?: string; // "al**********om"
name?: string; // "Alice Chen"
roles?: string[]; // ["admin", "sales"]
scopes?: string[]; // ["tool:crm:read", "tool:jira:write"]
plan?: string; // "team"
source: IdentitySource; // "auth0" | "okta" | "entra" | "cognito" | ...
raw: Record<string, unknown>; // Full JWT payload preserved
}
The claim-to-field mapping is set per IdP. Auth0 puts roles in permissions, Okta puts them in groups, and Entra ID puts scopes in scp. The identifiabl config normalizes all of this.
// Auth0
identifiabl({
issuer: "https://dev-xxxxx.us.auth0.com/",
audience: "https://gateway.local/api",
scopeClaim: "scope",
roleClaim: "permissions",
tenantClaim: "org_id",
})
// Okta
identifiabl({
issuer: "https://dev-xxxxx.okta.com",
audience: "https://gateway.local/api",
scopeClaim: "scp",
roleClaim: "groups",
tenantClaim: "tenant",
})
// Entra ID (Azure AD)
identifiabl({
issuer: "https://login.microsoftonline.com/{tenant}/v2.0",
audience: "api://{app-id}",
scopeClaim: "scp",
roleClaim: "roles",
})
The raw field keeps the full JWT payload. Custom claims from your IdP (department, cost center, clearance level) stay available downstream even if they map to no standard field.
What your backend receives
Without an ACP, your backend gets this:
POST /api/crm/contacts
Authorization: Bearer sk-shared-api-key-for-everyone
Content-Type: application/json
{"query": "show me all contacts in the pipeline"}
There is no user identity and no scope. You can’t filter results per user, and you can’t tell whether the request came from your CEO or a contractor.
With an ACP, your backend gets this:
POST /api/crm/contacts
x-user-uid: auth0|8f3a2b1c9d4e5f6a
x-user-scope: tool:crm:read
x-user-org: org_acme_corp
x-request-id: req_7f8a9b0c
Content-Type: application/json
{"query": "show me all contacts in the pipeline"}
Your backend code can now do this:
SELECT * FROM contacts
WHERE org_id = 'org_acme_corp'
AND pipeline_access IN ('tool:crm:read')
You get a verified identity, scoped permissions, tenant context and a trace. The user doesn’t log in again, because their existing SSO session carries through the AI layer.
How identity flows through the control pipeline
The identity object is used by every control layer downstream. Below is a simplified listing of the layers in governToolCall, in order. The real function has more branches, so read it as an illustration.
// 0a. Immutable platform rules (SSN, credit card, SSRF)
const immutable = checkImmutableRules(toolName, input);
// 0b. Delegation enforcement (if agent-to-agent)
// → Override auth.scopes with chain's effective scopes
// 1. Scope enforcement (validatabl-core)
const required = tenantCtx.policies?.toolRequiredScopes?.[toolName];
const permResult = checkPermissions(
{ scope: auth.scopes.join(" "), permissions: auth.claims?.permissions },
required,
);
// 2. ABAC policy rules (validatabl-core)
// defaultEffect here is the posture this tenant configured. The shipped
// default for a new workspace is audit-only (allow + log) until you set this.
const policyDecision = applyPolicies(
{ rules: tenantCtx.policies.rules, defaultEffect: "deny" },
{ identity: { sub: auth.sub, scope: auth.scopes.join(" ") }, tool: toolName },
);
// 3. Rate limit + budget preflight (limitabl-core)
const preflightResult = limitablEngine.preflight(
{ sub: auth.sub, orgId: auth.claims?.org_id, ip, tenantId },
{ workflowId },
);
// 4. Plan limit check (dynamic, Firestore-backed with per-tenant overrides)
const plan = await loadEffectivePlan(subscription?.planId ?? "free", tenantId);
const planCheck = checkPlanLimit(plan, { initiatingAgentsThisPeriod });
// 5. Content scanning + redaction (transformabl-core)
const transformResult = transformContent(inputStr);
Rate limits, budget caps, ABAC policies and scope checks all key off auth.sub, the verified identity. Rate limits and budgets are per user. ABAC policies evaluate the user’s roles and claims. Scope enforcement compares the user’s scopes to what each tool requires.
Immutable rules block dangerous input such as SSNs, credit card numbers and SSRF targets, whatever the tenant configured. They apply to action input on gateway-executed and proxied calls. Model-call and file-authoring tools are exempt, and client-side tools only get the cloud-metadata SSRF block.
Plan limits are dynamic. Base plans can be overridden per tenant in Firestore, so enterprise customers can have custom limits that merge on top of their plan.
Identity in the audit trail
Every tool call produces an audit record with the identity attached.
{
ts: "2026-04-01T14:23:07.841Z",
tenantId: "acme-corp",
requestId: "req_7f8a9b0c",
tool: "salesforce.query",
sub: "auth0|8f3a2b1c9d4e5f6a", // or SHA-256 hash if hashSub enabled
scopes: ["salesforce.*", "tool:crm:read"],
client: { name: "claude-desktop", version: "1.2.0" },
ok: true,
latencyMs: 142,
contentScan: {
piiDetected: false,
piiTypes: [],
riskScore: 12
}
}
When a compliance officer asks “who accessed customer data through the AI assistant last Tuesday?”, you can answer from one log in one format, with identity, timestamp and the policy decision chain.
If user IDs are sensitive in your setting (healthcare, say, where log aggregators shouldn’t see them), the hashSub option replaces sub with a SHA-256 hash. The hash is deterministic, so you can still correlate actions by the same user, but the original ID doesn’t appear in the log.
Identity providers supported
ACP works with any OIDC-compliant identity provider that issues RS256-signed JWTs and publishes a JWKS endpoint. That covers the major providers:
Verification works at the protocol level. If your IdP publishes a .well-known/openid-configuration endpoint with a jwks_uri, ACP can verify its tokens. There is no vendor integration, SDK or webhook to set up.
Why this differs from API keys
API keys are shared secrets. If one leaks, everyone holding it has the same access. You can’t attribute actions to specific users. Scoping a key to specific tools means a new key per tool per user, which nobody does. And keys don’t expire until someone rotates them.
JWTs are signed assertions. They carry the user’s identity, permissions and tenant context inside the token. They expire and they can be scoped. They can be verified without contacting the issuer, because verification uses public keys. They can’t be forged, because the private key stays at the IdP.
Service accounts identify the application, not the person. When an agent uses one, your audit trail says “the AI assistant accessed patient data,” not “Dr. Chen asked the AI assistant to access patient data.” Service accounts are necessary for background jobs. They are not enough for agent actions a human started.
With ACP, the human’s identity flows through the AI layer. Your backend sees the person, not just the pipe.
Running it without the cloud
The identity handling above is how ACP Cloud runs it. To run without the cloud, install the hook with --local. Rules are evaluated on the machine and nothing is sent. See install, explained. The framework SDKs (source) show what the gateway receives and how identity is attached to each call.
Get started → · Agent-to-agent governance → · Architecture deep dive → · View on GitHub →
Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex