By Nolan Sullivan, Founding Growth Engineertask-scoped credentials
Task-scoped credentials are short-lived, identity-bound secrets issued for one agent session, one person, one agent, one task, and revoked when the task ends. The agent never sees the raw long-lived secret for the upstream system, and if the session dies or the person is deprovisioned, the credential dies with it.
Task-scoped credentials exist because the common way to connect an AI agent to an upstream system is a long-lived secret, such as an API key pasted into a config file, or a shared service account every agent signs in with. That secret can keep working long after the task, the session, and the employee are gone. A task-scoped credential is a short-lived, just-in-time credential minted for the session in front of it, bound to the person driving it, and expired when the task completes, so the durable secret never enters the agent at all.
Why do long-lived agent secrets show up in security incident reports?
The shared service account is the default because it works on the first try, with one key for every agent and no further ceremony. The properties that make it convenient are the ones that make it a liability:
- It is over-scoped. A single credential has to cover everything any agent might ever do.
- It is held by every agent at once. A leak from any one of them is a leak of the whole grant.
- It leaves no trail. Every action arrives under the same name, which turns the incident-response question of who did this into a dead end.
Agents typically make each of those properties worse than they were for ordinary service integrations. An agent often holds its secret in places that weren’t designed to keep one, such as a dotfile, an environment variable, or a context window that can be coaxed into repeating what it has read. And a key in an agent config is usually tied to nothing in the directory, so when the engineer who set it up leaves, the key can keep working.
What kind of non-human identity an agent should hold instead is the subject of what is agent identity and what is non-human identity. The credential pattern on this page is how that identity reaches the upstream system without a durable secret riding along.
What does identity-bound mean for a task-scoped credential?
An identity-bound credential carries who is acting, not just what is allowed. The session behind it names the person from the directory as the subject and the agent workload as the actor, the pairing described in what is agent composite identity. When the agent requests a tool, the full tuple of tenant, subject, actor, and tool resolves to exactly one upstream credential, or an error. The resolution fails closed, never into a fallback, so a request that matches no grant gets a refusal instead of a shared key.
Binding the credential to a person is also what makes directory events reach agent access. Deprovision the person in the identity provider and the credentials bound to them stop being issued, which is the practical meaning of extending IAM to agents. The controls the organization already runs for people, including joiner and leaver events, govern the agents acting on their behalf with no parallel system to keep in sync.
Are task-scoped credentials the same as agent-scoped credentials?
No, and the difference is which boundary the credential dies at. A credential scoped to the agent alone is a standing secret that belongs to the agent workload. Every person who triggers the agent rides on the same credential, it lives as long as the agent does, and offboarding any one person never touches it. That is a service account by another name, with the over-scoping, the shared trail, and the offboarding gap described above.
A task-scoped credential narrows two further dimensions. It is bound to the person driving the run as well as the agent, and it lives for the task rather than for the agent’s lifetime. The agent still has a durable identity, its name, owner, and grants in the control plane, but no durable secret comes with it. That split is what keeps directory events meaningful. Deprovisioning a person stops issuance for every session they drove, and retiring an agent retires its identity without leaving a key to find and rotate.
How long do task-scoped credentials last before they expire?
Every credential expires when the task completes, the credential itself is never stored, and nothing has to remember to clean it up, so its whole life is measured in minutes. The agent identity product page shows this concretely. A live session in the gateway console carries a credential with a TTL of 23 minutes, counting down alongside the identity and policy checks for the same call.
Expiry handles the normal case, and revocation handles the urgent one, taking one call and applying immediately. Between the two, the failure modes of the long-lived key disappear. A credential captured mid-session is worthless minutes later, a session that dies takes its credential with it, and a person who is deprovisioned stops being a valid subject for issuance, so their agents lose access on the same directory event that disables their account.
How do task-scoped credentials compare to an API key in the agent config?
The API key in the config and the task-scoped credential answer the same integration need, so the difference is easiest to see property by property.
| Property | API key in the agent config | Task-scoped credential |
|---|---|---|
| Lifetime | Until someone remembers to rotate it | The task, measured in minutes |
| Who holds the secret | The agent, its config file, and anything that can read either | The agent holds only the session credential, and the raw secret never enters it |
| Scope | Everything the key can reach | The person, the agent, and the task |
| When the person leaves | The key can keep working | Issuance stops with the deprovisioned identity |
| The trail | No action tied to a person | Every action attributed to the person and agent |
The mechanism behind the right-hand column is just-in-time issuance, a short-lived credential minted at the moment of use, from a system that can bind it to the session requesting it. Where that system sits matters. Agents reach tools through an MCP gateway, which puts a single point on the path of every call, and that point is where a scoped credential can be issued per session instead of a standing secret being distributed to every agent config in the organization.
How does the Speakeasy AI Control Plane issue just-in-time task-scoped credentials?
The Speakeasy AI Control Plane ships the pattern as part of agent identity, and the issuance is the third step of a fixed sequence rather than a feature to wire up separately:
- Identity resolves first. The person signs in through the identity provider the organization already runs, and the session binds them as the subject with the agent workload as the actor.
- Policy evaluates before anything is minted. Every tool call is checked against rules scoped to the person, the system, and the action, and a matching deny always wins.
- The credential is minted for the task. The platform issues a short-lived credential bound to the person and the task. Agents never see raw secrets. Credentials are identity-bound and expire with the task, with no shared service accounts and no long-lived tokens.
- Every decision is recorded. Allow and deny both land in the audit stream under the directory identity that drove the call.
The model behind it is that identity lives in the control plane and credentials never do. The platform holds the agent’s name, its owner, its grants, and a rule saying that an assertion from a trusted issuer is that agent. It holds no secret for the agent and cannot reissue one, so there is no agent key for an attacker to steal or replay, and the tuple resolution described above fails closed rather than falling back to one. To see what your agents would hold under this model, and what they would stop holding, talk to us.