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

# Astro

> Mount KavachOS auth routes in an Astro app with `kavachAstro(kavach)`. Returns named handlers for a catch-all API page, with full MCP OAuth 2.1 support.

`kavachAstro(kavach, options?)` returns named route handlers `{ GET, POST, PATCH, DELETE, OPTIONS, ALL }`. Mount them in a catch-all API page so all KavachOS paths are handled. Use individual named exports or the `ALL` catch-all handler.

## Install

```bash theme={"system"}
pnpm add kavachos @kavachos/astro
```

## Setup

<Steps>
  <Step title="Create the kavach instance">
    ```typescript theme={"system"}
    // src/lib/kavach.ts
    import { createKavach, createMcpModule } from 'kavachos';

    export const kavach = createKavach({
      database: { provider: 'postgres', url: import.meta.env.DATABASE_URL },
      baseUrl: import.meta.env.AUTH_BASE_URL,
      mcp: {
        issuer: import.meta.env.AUTH_BASE_URL,
        audience: import.meta.env.MCP_BASE_URL,
      },
    });

    export const mcp = createMcpModule(kavach);
    ```
  </Step>

  <Step title="Create the catch-all route">
    Create `src/pages/api/kavach/[...path].ts`. The `[...path]` spread catches every sub-path under `/api/kavach/`.

    ```typescript theme={"system"}
    // src/pages/api/kavach/[...path].ts
    import { kavachAstro } from '@kavachos/astro';
    import { kavach, mcp } from '@/lib/kavach';

    const handlers = kavachAstro(kavach, { mcp });

    export const GET = handlers.GET;
    export const POST = handlers.POST;
    export const PATCH = handlers.PATCH;
    export const DELETE = handlers.DELETE;
    export const OPTIONS = handlers.OPTIONS;
    ```

    Or use the `ALL` handler to catch every HTTP method in one export:

    ```typescript theme={"system"}
    export const ALL = handlers.ALL;
    ```
  </Step>
</Steps>

<Warning>
  Astro requires `output: 'server'` or `output: 'hybrid'` in `astro.config.mjs` to enable API routes. Static output mode does not support server-side route handlers.
</Warning>

## Options

```typescript theme={"system"}
interface KavachAstroOptions {
  mcp?: McpAuthModule;     // enables MCP OAuth 2.1 endpoints
  basePath?: string;       // defaults to '/api/kavach'
}
```

## MCP endpoints

When `mcp` is passed, the MCP OAuth 2.1 endpoints are available at:

```
GET  /api/kavach/.well-known/oauth-authorization-server
GET  /api/kavach/.well-known/oauth-protected-resource
POST /api/kavach/mcp/register
GET  /api/kavach/mcp/authorize
POST /api/kavach/mcp/token
```

## Endpoint reference

| Method   | Path                    | Description               |
| -------- | ----------------------- | ------------------------- |
| `POST`   | `/agents`               | Create an agent           |
| `GET`    | `/agents`               | List agents               |
| `GET`    | `/agents/:id`           | Get an agent              |
| `PATCH`  | `/agents/:id`           | Update an agent           |
| `DELETE` | `/agents/:id`           | Revoke an agent           |
| `POST`   | `/agents/:id/rotate`    | Rotate token              |
| `POST`   | `/authorize`            | Authorize by agent ID     |
| `POST`   | `/authorize/token`      | Authorize by bearer token |
| `POST`   | `/delegations`          | Create delegation         |
| `GET`    | `/delegations/:agentId` | List delegation chains    |
| `DELETE` | `/delegations/:id`      | Revoke delegation         |
| `GET`    | `/audit`                | Query audit logs          |
| `GET`    | `/audit/export`         | Export audit logs         |

## Full example

```typescript theme={"system"}
// src/pages/api/kavach/[...path].ts
import { createKavach, createMcpModule } from 'kavachos';
import { kavachAstro } from '@kavachos/astro';

const kavach = createKavach({
  database: { provider: 'postgres', url: import.meta.env.DATABASE_URL },
  baseUrl: import.meta.env.AUTH_BASE_URL,
  mcp: {
    issuer: import.meta.env.AUTH_BASE_URL,
    audience: import.meta.env.MCP_BASE_URL,
  },
});

const mcp = createMcpModule(kavach);

const handlers = kavachAstro(kavach, { mcp });

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;
```