why identity matters
an agent is a program that calls apis on behalf of a human. that means two identity questions matter at every turn: who asked the agent to do this? and what is the agent allowed to do? get either one wrong and you have either a bad audit trail or a nasty security incident.
agentcore identity owns both sides. it brokers auth with your iam provider (cognito, okta, auth0, entra id), propagates user identity into the agent's execution context, and vends short-lived tokens for third-party services the agent needs to reach. no custom token storage, no refresh logic, no secrets in your code.
two directions
- inbound who called the agent. a user, a service, an automated workflow. identity attaches this to every invocation so your handler can read it, log it, and authorize actions against it.
- outbound what the agent can reach. the agent's own workload identity for aws resources; oauth tokens (per-user, per-provider) for third parties like google, slack, github.
reading inbound identity
in production the runtime injects the caller's principal into the invocation — you don't parse jwts, you don't validate signatures. identity has already done that. you just read.
the trace shows identity.init when the object is
constructed and identity.principal_read when the handler
reads it. in cloudwatch you get the same events, tagged with the
invocation's trace id — so you can audit which user triggered which
action across an entire workflow.
outbound — oauth without the dance
the classic pain: an agent needs to read a user's google calendar. you'd normally build an oauth 2 flow, store refresh tokens, rotate them, deal with revocation. identity takes that over. you say "i want a token for google calendar, read-only"; it hands you one.
behind the scenes, identity ran the oauth dance with the user the first time this agent needed access. it stored the refresh token server-side, keyed to (user, provider, scope). subsequent calls from any agent running as that user get a fresh access token in one api call.
the mock returns deterministic fake tokens so you can see the shape. in production you pass the returned token directly to the provider's api.
scoping tools by principal
the security payoff is obvious once you combine identity + gateway. tools can be bound to scopes. a user without the right scope doesn't see the tool, so the llm can't accidentally call it.
in the sandbox we write the toolsFor function explicitly.
in production, identity + gateway enforce it declaratively — you attach
a scope to each tool, and the runtime only presents tools whose scopes
the invoking principal holds. the agent framework never gets to try and
fail; it's never offered the choice.
Identity wrapper shown here, the production
typescript sdk also exposes withAccessToken and
withApiKey helpers that decorate any async function with
injected credentials — use those when you want a tool implementation
to receive the token transparently rather than asking for it.
iam you don't have to write
a common reason teams avoid building agents: iam fatigue. every new tool means a new policy, every new policy means a review, every review takes a week. identity flips that. you declare the capabilities the agent needs — "read calendar for users in this okta group" — and the service maps it to the right permissions, scopes, and audit events.
that's not iam-less; it's iam hidden from you. the policies still exist. you just don't write them in json.
next: browser and code interpreter — two tools you get for free.