# Agent Authentication & Registration

Rembr supports agent registration and OAuth 2.0 authentication for MCP-compatible agents.

## Agent Registration

New agents can self-register via the Dynamic Client Registration endpoint (RFC 7591):

```
POST /api/register
```

### Request

| Field | Required | Type | Description |
|---|---|---|---|
| `client_name` | Yes | string | Human-readable name for your agent (max 120 chars) |
| `redirect_uris` | Yes | string[] | HTTPS or localhost redirect URIs (1-10) |
| `grant_types` | Optional | string[] | Defaults to `["authorization_code", "refresh_token"]` |
| `scope` | Optional | string | Requested OAuth scopes |

### Response (201 Created)

| Field | Type | Description |
|---|---|---|
| `client_id` | string | Your unique client identifier |
| `client_secret` | string | Your client secret (store securely) |
| `registration_access_token` | string | Token for future client updates |
| `registration_client_uri` | string | Endpoint to manage your registration |

### Rate Limiting

- Maximum 10 registration attempts per minute per IP
- Returns `429` with `rate_limited` error on exceedance

## Authentication

### OAuth 2.0 Authorization Code Flow

1. Redirect to the authorization endpoint:
   ```
   GET /api/oauth/authorize?response_type=code&client_id={id}&redirect_uri={uri}&scope=openid%20mcp:full&code_challenge={S256}&code_challenge_method=S256
   ```

2. Exchange the authorization code for a token:
   ```
   POST /api/oauth/token
   ```
   Send `client_id`, `client_secret`, `code`, `grant_type=authorization_code`, and `code_verifier`.

### Supported Scopes

- `openid` — OpenID Connect identity
- `profile` — Agent profile information
- `email` — Email address
- `mcp:full` — Full MCP access

### Token Endpoint Auth Methods

- `client_secret_post` — Send credentials in request body
- `client_secret_basic` — Send via HTTP Basic auth header

## Identity Types

Rembr supports:

- **OAuth MCP clients** — Agents registering via RFC 7591 dynamic client registration
- **API key agents** — Agents authenticating with `X-API-Key` headers

## OAuth Metadata

Full OAuth 2.0 Authorization Server Metadata is available at:

[/.well-known/oauth-authorization-server](/.well-known/oauth-authorization-server)

This metadata includes issuer, endpoints, supported grant types, response types, and code challenge methods per RFC 8414.

## Security

- Redirect URIs must use HTTPS or localhost
- PKCE (S256) is required for all authorization requests
- Client secrets are generated with 256-bit cryptographically secure random bytes