# auth.md — Agent Authentication & Registration

**Resource:** `https://cyberprivateeye.com`
**Maintainer:** cases@cyberprivateeye.com

Cyber Private Eye allows AI agents to authenticate to its protected APIs
using OAuth 2.0 bearer tokens. This file describes how an agent registers
and obtains credentials.

## 1. Discover the authorization server

Read the OAuth 2.0 Authorization Server Metadata at:

```
GET /.well-known/oauth-authorization-server
```

It returns `authorization_endpoint`, `token_endpoint`, `jwks_uri`,
`grant_types_supported`, `scopes_supported`, and an `agent_auth` block.

The protected resource metadata is published at:

```
GET /.well-known/oauth-protected-resource
```

## 1a. Agent Auth metadata

The machine-readable `agent_auth` block (also embedded in
`/.well-known/oauth-authorization-server`) is reproduced here so agents can
discover registration, identity, credential, claim, and revocation endpoints
without parsing the full OAuth metadata:

```json
{
  "agent_auth": {
    "register_uri": "https://cyberprivateeye.com/auth.md",
    "supported_identity_types": ["email", "did", "oauth"],
    "credential_types": ["bearer", "dpop"],
    "claims_endpoint": "https://cyberprivateeye.com/hcgi/platform/api/collections/users/auth-refresh",
    "revocation_uri": "https://cyberprivateeye.com/hcgi/platform/api/oauth2/revoke"
  }
}
```

## 2. Register your agent

Send a POST to the `register_uri` advertised in the `agent_auth` block
(currently this file's location, `/auth.md`, which documents manual
registration). Provide:

- `client_name` — a human-readable name for the agent
- `contact` — an email address
- `supported_identity_types` — one of `email`, `did`, `oauth`
- `credential_types` — `bearer` and/or `dpop`
- `redirect_uris` — callback URIs for the authorization_code grant

A maintainer will provision a `client_id` / `client_secret` pair and reply
with the registered credentials and allowed scopes.

## 3. Obtain an access token

Use the `token_endpoint` from the metadata with one of the supported grant
types (`authorization_code`, `client_credentials`, or `refresh_token`).
Request only the scopes you need:

- `case:read` — read case inquiry status
- `case:write` — submit a case inquiry
- `contact:write` — submit a contact message
- `pricing:read` — read pricing and payment status

## 4. Call the API

Send the token as a bearer header:

```
Authorization: Bearer <access_token>
```

against `https://cyberprivateeye.com/hcgi/api`.

## 5. Revocation & claims

Tokens can be revoked at the `revocation_uri` from the `agent_auth` block.
User claims are available at the `claims_endpoint`
(`/hcgi/platform/api/collections/users/auth-refresh`).

## Security notes

- All endpoints are HTTPS only.
- PKCE (`S256`) is required for the authorization_code grant.
- Case files are purged 30 days after delivery unless retention is requested.