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

# A Secure Agent Architecture

> The building blocks of secure credential delegation for agents.

The failures above come from using credentials that were not designed for delegated, autonomous execution. The fix is an identity model for agents: scoped, auditable, and revocable.

## Agents get their own identity

Each agent is a distinct principal, not a shared bot account.

```text theme={"system"}
Before:
Agent A --\
Agent B ----> github-bot
Agent C --/

After:
Agent A -> agent:pr-reviewer
Agent B -> agent:issue-triage
Agent C -> agent:release-notes
```

With per-agent identity, you can apply policy, audit behavior, and revoke access at the right granularity.

## Users delegate explicitly

Users approve what an agent can do through OAuth 2.0 consent. The agent receives delegated access, not the user's full session.

From the user's perspective, this is what happens:

<Steps>
  <Step title="Agent requests access">
    Your agent starts a task that needs GitHub access. It initiates an OAuth flow through Kontext.
  </Step>

  <Step title="User sees a consent screen">
    The consent screen shows exactly what is being requested — which integrations, what scopes, how long:

    ```text theme={"system"}
    PR Reviewer is requesting access:
    - Read pull requests
    - Post review comments
    - No org admin access
    - Expires in 1 hour
    ```
  </Step>

  <Step title="User approves once">
    One approval per session. The agent receives a scoped token. The user can revoke it at any time from the Kontext dashboard.
  </Step>
</Steps>

Under the hood, agents use PKCE (public-client safe OAuth):

```text theme={"system"}
Agent                         Auth Server                    User
 | generate code_verifier         |                           |
 | send code_challenge ---------->|                           |
 |                                | show consent -----------> |
 |                                | <--------- approve -------|
 | send code_verifier ----------->|                           |
 |<------ scoped access token ----|                           |
```

Only the party that initiated the flow can complete it.

## Credentials are scoped and short-lived

Compare static tokens with per-request delegated credentials:

```typescript theme={"system"}
// BEFORE: static secret for all requests
const GITHUB_TOKEN = process.env.GITHUB_TOKEN;

server.tool("review_pr", async ({ repo, pr }) => {
  const github = new Octokit({ auth: GITHUB_TOKEN });
  // ... read PR, post review
});
```

```typescript theme={"system"}
// AFTER: delegated credential per request
server.tool("review_pr", async ({ repo, pr }, { authInfo }) => {
  const github = await kontext.require("github", authInfo.token);

  // ... read PR, post review
});
```

The agent does not carry one broad secret forever. It receives a short-lived delegated credential at request time, and Kontext enforces policy and lifetime centrally during exchange.

<Info>
  **Fresh credentials, every time.** The agent does not store a token and reuse it across tasks. Each call to `kontext.require()` returns a credential scoped to the current request with its own TTL. When it expires, the agent requests a new one. There is no single long-lived secret that grants access to everything.
</Info>

## Policy enforcement is centralized

A control plane evaluates each request across layered policy.

```text theme={"system"}
Request --> Org policy --> User consent --> Agent permissions --> Issue credential

Example:
- Org policy: no write access to production repos
- User consent: read-only for selected repos
- Agent permissions: PR reviewer can call GitHub, not Slack
```

All layers must pass before any credential is issued.

## Every action is audited

Each credential issuance and API call is logged with actor, delegation context, scope, and outcome.

```json theme={"system"}
{
  "agent": { "id": "agent:pr-reviewer-v2", "name": "PR Reviewer" },
  "user": { "id": "user:alice@acme.com", "name": "Alice Chen" },
  "integration": "github",
  "scopes": ["pulls:read", "pulls:write"],
  "target": "acme-corp/backend",
  "expires_in": "600s",
  "policy_evaluation": {
    "org_policy": "allow",
    "user_consent": "allow",
    "agent_permissions": "allow"
  }
}
```

```text theme={"system"}
09:32:14 credential.issued  agent:pr-reviewer -> github
09:32:15 api.call           GET /repos/acme/backend/pulls/42
09:32:18 api.call           POST /repos/acme/backend/pulls/42/reviews
09:32:18 credential.expired agent:pr-reviewer -> github
```

## Revocation is surgical

If one agent misbehaves, revoke that agent only.

```text theme={"system"}
Revoke agent:issue-triage:
- agent:pr-reviewer   still running
- agent:issue-triage  revoked
- agent:release-notes still running
- CI pipelines        unaffected
```

Incident response is proportional to the blast radius.

## Fits your existing stack

This layer augments existing IAM, IdP, and secrets systems.

```text theme={"system"}
Agents --> Kontext credential layer --> Existing OAuth/IdP/IAM --> External APIs
```

You keep existing infrastructure and add agent-aware delegation where current systems are missing primitives.

***

This is the architecture [Kontext](https://kontext.security) implements. Start with the [quickstart](/getting-started/quickstart).