# Dosu — Agent Authentication

> How AI agents authenticate to the Dosu API and the Dosu MCP server.

Dosu hosts a Model Context Protocol (MCP) server and a REST API at `https://api.dosu.dev`. This
document follows the [auth.md](https://workos.com/auth-md) convention so an agent
can discover, register, and authenticate on a user's behalf without prior setup.

## Step 1 — Discover

Fetch the discovery metadata from the resource server. Both documents are public.

```http
GET /.well-known/oauth-protected-resource
Host: api.dosu.dev
```

```http
GET /.well-known/oauth-authorization-server
Host: api.dosu.dev
```

The authorization-server metadata includes an `agent_auth` block whose `skill`
field points back at this document.

## Endpoints

- MCP server (Streamable HTTP): `https://api.dosu.dev/v1/mcp`
- OpenAPI specification: `https://api.dosu.dev/openapi.json`
- Interactive API docs: `https://api.dosu.dev/docs`

## Step 2 — Pick a method

Dosu accepts two credential types.

### OAuth 2.0 (recommended)

Authorization Code + PKCE with Dynamic Client Registration (RFC 7591). A client
with no pre-issued identity registers itself, then completes the standard
browser-based authorization-code flow against Dosu's authorization server.

- Register a client: `POST https://wldmetsoicvieidlsqrb.supabase.co/auth/v1/oauth/clients/register`
- Authorize: `GET https://wldmetsoicvieidlsqrb.supabase.co/auth/v1/oauth/authorize`
- Token: `POST https://wldmetsoicvieidlsqrb.supabase.co/auth/v1/oauth/token`

Send the resulting bearer token on every request:

```http
POST /v1/mcp
Host: api.dosu.dev
Authorization: Bearer <access_token>
```

### API key

Create a key in the dashboard under Settings → Account → API keys, then send it
in the `X-Dosu-API-Key` header. Keys start with `sk_user_`.

```http
POST /v1/mcp
Host: api.dosu.dev
X-Dosu-API-Key: sk_user_...
```

## Step 3 — Use the access token

Once authenticated, call `tools/list` over the Streamable-HTTP transport at
`https://api.dosu.dev/v1/mcp` and use only the tools it returns. With a deployment selected, use
`read_knowledge` to retrieve team knowledge. Without a deployment, use
`find_public_library` to discover an indexed project before calling
`ask_public_library`. REST endpoints are described in the OpenAPI specification.