Agent-friendly product design is becoming an identity control problem

At a glance

What this is: This is a design guide for making APIs, documentation, UIs, and auth flows usable by LLM-powered agents, with the key finding that agent-friendly systems need literal contracts and predictable identity handling.

Why it matters: It matters because product design now intersects with NHI governance, since agents consuming APIs and OAuth flows behave like non-human identities that IAM teams must scope, monitor, and revoke.

👉 Read WorkOS's guide on building agent-friendly products for LLM users

Context

LLM-powered agents are now interacting with products as users, which means the old assumption that only humans read documentation, click UIs, or complete auth flows no longer holds. For identity teams, this is a governance problem as much as a product design problem, because agent access has to be predictable enough to authorize and observable enough to control.

Agent-friendly design is really contract design. When docs are literal, schemas are stable, errors are actionable, and authentication is programmatic, the product becomes usable by non-human actors without forcing brittle workarounds that blur accountability or expand standing access.

Key questions

Q: How should security teams govern AI agents that use APIs and OAuth flows?

A: Treat AI agents as non-human identities with scoped credentials, explicit ownership, and a defined offboarding path. Use programmatic auth, per-agent tokens where possible, and telemetry that ties activity to a specific agent rather than a shared service account. The goal is to make access observable, revocable, and limited to the workflow the agent actually needs.

Q: Why do agent-friendly products create new NHI governance requirements?

A: Because the moment a product supports non-human users, it starts issuing machine identities that can be over-scoped, reused, or forgotten. That creates the same lifecycle risk seen with service accounts and API keys, plus new exposure from documentation, UI dependencies, and automated retries. Governance has to follow the identity, not the interface.

Q: What breaks when documentation is not clear enough for AI agents?

A: Agents do not reliably infer missing context, so vague docs turn into failed calls, wrong parameters, or repeated retries. In practice, bad documentation becomes an access control problem because the agent either cannot complete the task or attempts the task in ways the product never intended. Clear schemas and consistent examples reduce that failure surface.

Q: How can teams tell whether an agent is using product access safely?

A: Look for stable request patterns, clean attribution, predictable error recovery, and usage that stays within the documented scope of the token or key. If the agent is chaining tools unexpectedly, retrying aggressively, or touching endpoints outside its stated purpose, the identity is drifting beyond the intended boundary and needs review.

Technical breakdown

Why literal API contracts matter for agent access

LLM agents do not infer intent the way humans do. They parse parameter names, response shapes, and status codes literally, which makes ambiguity a failure mode rather than a usability nuisance. Consistent JSON, explicit required fields, and structured errors let an agent complete a task without guessing. That also means documentation is part of the runtime control surface, because the agent is effectively consuming the docs as machine-readable policy. If the contract is vague, the agent may retry incorrectly, call the wrong endpoint, or stop entirely.

Practical implication: Treat API documentation, schemas, and error payloads as enforceable control surfaces, not supporting material.

How agent-friendly authentication changes NHI governance

Agents cannot reliably navigate browser-first login flows, CAPTCHA challenges, or multi-step human verification. That pushes products toward API keys, OAuth 2.0, scoped tokens, and refreshable programmatic auth. For IAM teams, the issue is not whether an agent can authenticate, but whether its access can be separated by purpose, monitored per identity, and revoked without breaking unrelated workflows. In NHI terms, the access path needs enough structure to support least privilege, auditing, and clean offboarding.

Practical implication: Scope agent credentials by function and ownership, then make rotation, revocation, and usage attribution operationally simple.

Stable UI patterns are a control surface for non-human users

When agents use interfaces through headless browsers or vision tools, they depend on stable selectors, semantic labels, and visible state changes. Dynamic classes, unlabeled buttons, and hidden loading states turn the UI into a brittle target. This is less about visual polish and more about whether the interface can be interpreted reliably by a machine. In practice, UI consistency becomes a prerequisite for safe delegation, especially when the agent can trigger actions that affect billing, customer data, or operational state.

Practical implication: Standardise semantic markup and stable identifiers for any workflow that a non-human actor might execute.

Breaches seen in the wild

• Moltbook AI agent keys breach — Moltbook breach exposed 1.5M AI agent keys.
• AI LLM hijack breach — attackers used stolen AWS access keys to hijack Anthropic LLM models on Bedrock.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Agent-friendly design is an identity problem disguised as a product experience problem. Once LLM-powered systems can read docs, call APIs, and complete workflows, they should be treated as non-human identities with their own access patterns, failure modes, and revocation needs. That means the governance question is not just whether an agent can use the product, but whether the product can safely distinguish agent access from human access across the full lifecycle. Practitioners should recognise that machine usability and identity governance are now the same control domain.

Literal contracts reduce ambiguity, but they also expose weak identity assumptions. If an API only works when a human compensates for missing context, the access model is already too fragile for non-human actors. The issue is not that agents are smart or dumb, but that they require deterministic inputs, consistent outputs, and predictable retries. That aligns tightly with OWASP-NHI and zero trust thinking, where identity verification and authorisation boundaries must survive imperfect clients. Practitioners should measure how much of their current access model depends on human interpretation.

Agent onboarding should be governed like NHI onboarding, not treated as casual automation. The moment a product supports API keys, OAuth flows, or agent-specific tokens, it is creating identities that can accumulate privilege, generate usage cost, and outlive the workflow that created them. That is the same lifecycle problem identity teams already manage for service accounts, only with more runtime variability and less predictable behaviour. Practitioners should classify every agent-facing credential as a governed identity with an owner, scope, and offboarding path.

Stable UI design is a hidden access control layer. When a non-human actor depends on buttons, selectors, and page structure, the interface itself becomes part of the control plane. Broken selectors and unlabeled actions do more than frustrate automation, they can redirect an agent into unintended behaviour or prevent it from completing a legitimate task. That is why interface consistency belongs in the identity governance conversation, especially where delegated actions touch sensitive systems. Practitioners should review UI workflows as if they were privileged machine interfaces, because increasingly they are.

From our research:

• 92% agree governing AI agents is critical to enterprise security, yet only 44% have implemented any policies to do so, according to AI Agents: The New Attack Surface report.
• Only 52% of companies can track and audit the data their AI agents access, leaving 48% with a complete blind spot for compliance and breach investigation.
• That visibility gap is why the next governance question is not whether agents exist, but whether identity controls can distinguish, scope, and revoke them at runtime.

What this signals

Agent-friendly design will force IAM teams to treat documentation, APIs, and UI patterns as part of the identity boundary. When a non-human actor can only function if the product is deterministic, the control problem moves upstream into product engineering. Teams that already align access controls to Zero Trust Architecture should extend that discipline to machine-facing contracts and track them alongside the Ultimate Guide to NHIs.

At 92% of organisations saying AI agent governance is critical but only 44% having policies in place, the market is signalling a governance lag rather than a technology gap. That means product teams, IAM teams, and compliance teams need a shared model for agent onboarding, monitoring, and offboarding before usage expands further. The practical test is whether the organisation can describe, attribute, and revoke agent access with the same clarity it applies to service accounts.

For practitioners

• Inventory agent-facing entry points Map every API, auth flow, and UI path that a non-human actor can use, then assign an owner and lifecycle policy to each one. Include documentation pages and sandbox endpoints because agents consume those as operational instructions, not background material.
• Standardise credential scope and revocation Issue per-agent credentials where possible, scope them to a single function, and make rotation and revocation routine. Track usage by key, token, or client so you can separate one agent’s behaviour from another and from human activity.
• Treat documentation as a machine contract Keep endpoint descriptions, request examples, and error payloads aligned with the actual runtime behaviour. If an agent can only succeed by guessing a field name or interpreting inconsistent status codes, the control surface is too loose for safe delegation.
• Harden the interface for non-human execution Use semantic HTML, stable IDs, visible state changes, and explicit labels for every workflow that could be driven by a browser automation tool or vision model. Review critical UI actions the same way you would review a privileged API.
• Build agent monitoring into identity telemetry Log requests with agent attribution, track retries and tool usage, and flag unusual request velocity or cross-system chaining. Agent behaviour is only governable when it is observable at the identity layer, not just at the application log level.

Key takeaways

• AI agents turn product usability into an identity governance issue because their access must be explicit, scoped, and revocable.
• Clear docs, predictable APIs, stable UI patterns, and programmatic auth all reduce ambiguity for non-human users, but they also expose whether current IAM controls are too human-centric.
• Security teams should govern agent-facing credentials as NHI lifecycles, with ownership, telemetry, and offboarding built in from the start.

Key terms

• Agent-Facing Interface: An agent-facing interface is any API, UI, or documentation path designed to be consumed by a non-human actor. It has to behave like a machine contract, with stable structure, explicit inputs, and predictable outputs so automated clients can complete tasks without human interpretation.
• Non-Human Identity: A non-human identity is any machine or software identity that can authenticate and access systems, including API keys, tokens, certificates, service accounts, and AI agents. In practice, it must be governed with ownership, scope, monitoring, and lifecycle controls just like a human identity, often more tightly.
• Machine Contract: A machine contract is the explicit technical agreement a system exposes to automated consumers through documentation, schemas, error responses, and UI structure. It defines how a non-human actor is expected to behave, and it becomes a security boundary when access depends on strict, repeatable interpretation.
• Agent Attribution: Agent attribution is the ability to tie each request, action, retry, and cost event back to a specific non-human actor. It matters because shared credentials and anonymous automation hide misuse, make revocation harder, and prevent security teams from understanding which identity actually performed a task.

Deepen your knowledge

Agent-friendly product design is covered in the NHI Foundation Level course, the industry's only accredited NHI security programme. If you are trying to govern API keys, OAuth flows, and agent-facing workflows together, it is a useful starting point.

This post draws on content published by WorkOS: How to build agent-friendly products. Read the original.