Skip to main content
When an agent runs inside your AI coding assistant and needs Endor Labs data, it doesn’t use your API key directly. Instead, endorctl exchanges your credentials for a short-lived, read-only token that Endor Labs attributes to you. The agent reaches the API under that token and never sees your raw credentials. The Agent Kit agents use this mechanism automatically. Every Endor Labs API command they run goes through endorctl agent api, labeled with the agent’s catalog id, so you don’t set anything up per agent.

​
How it works

The agent calls endorctl agent api, which mirrors the endorctl api surface but runs every request under a delegated token.
  1. endorctl reads your credentials, the same ones endorctl api uses.
  2. It exchanges them with Endor Labs for a delegated token. The token is read-only, tied to you, and grouped into a single agent session.
  3. It caches the token on disk and runs the API request under it.
  4. Endor Labs enforces the read-only limit on its side and denies any request that would change state.
The token expires after one hour. endorctl refreshes it automatically, so the agent keeps working across a session without re-authenticating each call.

​
Before you begin

You can use any credentials that endorctl already supports, except a browser or single sign-on session. The most common choice is an Endor Labs API key, set through these environment variables.
An Endor Labs token in ENDOR_TOKEN and keyless CI credentials, such as GitHub OIDC, also work. The one credential Endor Labs refuses to exchange is a browser or single sign-on session. If you normally sign in through your identity provider, create an API key for agent use. See API keys to create one.

​
Run API requests as a delegated agent

Run endorctl agent api with the same arguments you would pass to endorctl api. The following command lists findings in a namespace under a delegated token.
The --agent-id value is an attribution hint that labels which agent made the request. Endor Labs agents pass their catalog agent id, and that id is what the agent activity view reports against. You can also set it with the ENDOR_AGENT_ID environment variable. It doesn’t grant or restrict access. Get a single resource by UUID.

​
What a delegated agent can and can’t do

endorctl agent api exposes the same subcommands as endorctl api.
  • list and get succeed, subject to your permissions.
  • create, update, and delete exist as subcommands, but Endor Labs denies them with a permission error because a delegated token is read-only.

​
Manage the session cache

endorctl caches delegated tokens under your configuration directory, by default ~/.endorctl/agent-sessions/. It stores each token in its own file that only your user account can read. A cached token stays valid for one hour. Because endorctl caches the token, an agent that already holds a valid token keeps working offline. Only a request that needs a new token fails without network access. There’s no dedicated command to clear the cache. To force a fresh exchange, delete the directory.

​
Troubleshooting

endorctl couldn’t find usable credentials. Set an API key in ENDOR_API_CREDENTIALS_KEY and ENDOR_API_CREDENTIALS_SECRET, or a token in ENDOR_TOKEN, and confirm the credential is active in your tenant.
A delegated token requires a non-interactive credential. Endor Labs refuses to exchange a browser or single sign-on session. Create an API key and set the credential environment variables.
The agent tried a request that changes state, and Endor Labs rejected it. Depending on the endpoint, the error reads read-only agent may not invoke a mutating method or a generic permission denial. Make the change through your source control provider, such as a pull request, instead of writing to Endor Labs.