Short answer: A self-describing credential is a token that carries everything an AI agent needs to connect, so the agent can start working without separate documentation or configuration. The agent reads the exchange location out of the token itself, exchanges it once, and gets back its access token plus the scopes it was granted, the endpoints it can call, and the request schemas for each one. It turns “here is a token” into “the agent is operational” in a single step, with no shared secrets and no manual setup.
Why connecting an AI agent to an app is usually painful
The normal way an agent gets access to an app is a scavenger hunt. Someone reads the API docs, finds the base URL, configures endpoints, wires up an auth flow, and pastes in a key. Every new integration repeats the work, and every step is a chance to over-grant access or leak a secret. The agent ends up holding a broad credential and a hand-built map of what to do with it.
A self-describing credential removes that work by putting the map inside the token.
How a self-describing credential works
Two things make the token self-describing.
- The agent finds the exchange point on its own. The location where the token is redeemed is encoded in the token itself, so the agent determines where to exchange it without external instructions, documentation, or a separate discovery service.
- One exchange returns everything. When the agent exchanges the token, it receives its scoped access token along with operational instructions in the same response: which app it is talking to, where to send requests, the specific endpoints its scope allows, and the field-level request schema for each of those endpoints.
The result is that an agent goes from holding a credential to making correct, in-scope calls without a human writing integration code for it.
What a self-describing credential gives you that an API key does not
An API key is a bare secret. It says nothing about who granted it, what it is for, or what the agent may do with it, and it usually unlocks far more than the task at hand. A self-describing credential is the opposite on every count:
- Zero configuration. No docs, no endpoint list to maintain, no shared setup between your app and the agent.
- Least privilege by construction. The endpoint map the agent receives is filtered to the scope the user approved. A read-only agent is only ever shown read endpoints, so it cannot discover or call anything beyond its grant.
- No shared secrets to leak. The agent does not need pre-shared configuration or credentials to learn how to operate, because the token carries what it needs.
Does a self-describing credential work with any AI agent?
It works directly with any agent that can make HTTP requests, such as Claude Code, Codex, or a custom agent, because those agents can read the token and call the exchange endpoint themselves. Chat interfaces that cannot make arbitrary calls, like Claude Desktop or ChatGPT, connect through an MCP server that acts as the bridge. Either way the agent gets a token it can act on immediately.
Where this fits with user-mediated authorization
A self-describing credential is how the agent operates. User-mediated authorization is how the agent got the credential in the first place: the user approved a scope and the token was delivered to the user, not pushed to the agent through an automated channel. Together they mean the user decides what an agent may do, and the agent can then do exactly that, and nothing more, without a manual integration. For the granting side, see what user-mediated authorization for AI agents means.
Frequently asked questions
Is a self-describing credential the same as an API key?
No. An API key is a bare secret with no built-in meaning, usually granting broad access. A self-describing credential tells the agent where to exchange it and, after exchange, returns the scopes, endpoints, and request schemas the agent is allowed to use, so it operates in-scope without extra configuration.
How does the agent know where to send the token?
The exchange location is encoded in the token itself. The agent reads it directly from the credential and sends its exchange request there, with no external documentation or separate discovery step.
What does the agent get back when it exchanges the token?
A scoped access token plus operational instructions in one response: the app it is connecting to, where to send requests, the endpoints permitted by its scope, and the field-level request schema for each. That is enough for the agent to start making correct calls immediately.
Does the token expose every endpoint in the app?
No. The endpoint map is filtered to the scope the user approved. An agent granted read access is only shown read endpoints, so a self-describing credential stays least-privilege rather than handing over the whole surface of the app.
The self-describing credential is one of the inventions behind AgentAdmit, and it is patent pending.
AgentAdmit is the authorization layer for the agent economy: user-mediated, scoped authorization for AI agents, with a patent-pending self-describing token that makes an agent operational in one exchange. Scoped. Revocable. Auditable. See how AgentAdmit works.
Related reading: how to let an AI agent access a user’s account safely and MCP security: how to let an AI agent access user data safely.