# auth.md — agenticplug.ai agent authentication

agenticplug.ai exposes a Model Context Protocol (MCP) server with read-only,
public knowledge tools. Access is gated by OAuth 2.1 so that tokens are properly
scoped and signed — there is **no human login or consent gate**, because the
underlying data is public. Any agent can self-register and obtain a token
programmatically.

## Quick start (client_credentials)

1. **Register** a client (RFC 7591 Dynamic Client Registration):

   ```
   POST https://agenticplug.ai/oauth/register
   Content-Type: application/json

   { "client_name": "my-agent", "grant_types": ["client_credentials"] }
   ```

   Response includes `client_id` and `client_secret`.

2. **Get a token** (client_credentials grant):

   ```
   POST https://agenticplug.ai/oauth/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=client_credentials&client_id=...&client_secret=...
   ```

3. **Call the MCP server** with the bearer token:

   ```
   POST https://agenticplug.ai/api/mcp
   Authorization: Bearer <access_token>
   ```

A browser/interactive agent may instead use the **authorization_code + PKCE**
grant via `https://agenticplug.ai/oauth/authorize` (register with
`token_endpoint_auth_method: "none"` and a `redirect_uris` entry).

## Discovery documents

- Authorization Server metadata (RFC 8414): `https://agenticplug.ai/.well-known/oauth-authorization-server`
- Protected Resource metadata (RFC 9728): `https://agenticplug.ai/.well-known/oauth-protected-resource`
- JWKS (token verification keys): `https://agenticplug.ai/.well-known/jwks.json`
- MCP Server Card (SEP-1649): `https://agenticplug.ai/.well-known/mcp/server-card.json`

A 401 from `https://agenticplug.ai/api/mcp` returns a `WWW-Authenticate` header pointing to
the protected-resource metadata above.

## agent_auth

```json
{
  "agent_auth": {
    "skill": "oauth2",
    "register_uri": "https://agenticplug.ai/oauth/register",
    "protected_resource_metadata": "https://agenticplug.ai/.well-known/oauth-protected-resource",
    "authorization_servers": ["https://agenticplug.ai"],
    "grant_types_supported": ["client_credentials", "authorization_code"],
    "code_challenge_methods_supported": ["S256"],
    "scopes_supported": ["mcp:read"],
    "identity_types_supported": ["anonymous"],
    "resource": "https://agenticplug.ai/api/mcp"
  }
}
```

The resource exposes only public, read-only information, so the issued identity
is anonymous; tokens carry the `mcp:read` scope and are valid solely for the
`https://agenticplug.ai/api/mcp` resource.