> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delegated agent credentials

> <Badge color="green">Beta</Badge> <br /> How an agent reaches Endor Labs data under a short-lived, read-only token attributed to you.

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](/secure-ai-coding/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`](/developers-api/cli) 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.

```bash theme={null}
export ENDOR_API_CREDENTIALS_KEY=<your-api-key>
export ENDOR_API_CREDENTIALS_SECRET=<your-api-secret>
```

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](/platform-administration/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.

```bash theme={null}
endorctl agent api list --resource Finding --namespace <your-namespace> --agent-id ai-sast-remediation
```

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](/secure-ai-coding/agents-hub/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.

```bash theme={null}
endorctl agent api get --resource Project --uuid <project-uuid> --namespace <your-namespace>
```

## 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.

```bash theme={null}
rm -rf ~/.endorctl/agent-sessions/
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent session requires credentials">
    `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.
  </Accordion>

  <Accordion title="Browser or SSO login can't be exchanged">
    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.
  </Accordion>

  <Accordion title="Permission denied on create, update, or delete">
    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.
  </Accordion>
</AccordionGroup>