# auth.md — Agent Authentication for Crevio

Crevio is an AI-powered platform that runs a creator's business — products,
checkouts, customers, payments, marketing, sites, and growth. This document tells
an autonomous agent how to obtain credentials and call Crevio on a user's behalf.

Machine-readable metadata:

| Document | URL |
| -------- | --- |
| Authorization server metadata (RFC 8414) | `https://crevio.co/.well-known/oauth-authorization-server` |
| Protected resource metadata (RFC 9728) | `https://crevio.co/.well-known/oauth-protected-resource` |
| API catalog (RFC 9727) | `https://crevio.co/.well-known/api-catalog` |
| AI catalog (MCP discovery) | `https://crevio.co/.well-known/ai-catalog.json` |
| MCP server card | `https://mcp.crevio.co/mcp/server-card` |
| Agent skills index | `https://crevio.co/.well-known/agent-skills/index.json` |
| Web Bot Auth key directory | `https://crevio.co/.well-known/http-message-signatures-directory` |

## Resources you can get a token for

| Resource | Identifier | Transport |
| -------- | ---------- | --------- |
| REST API | `https://api.crevio.co` | HTTPS + `Authorization: Bearer` |
| MCP server | `https://mcp.crevio.co/mcp` | MCP Streamable HTTP |

Both accept OAuth 2.1 access tokens issued by `https://crevio.co`. The REST API
additionally accepts long-lived account API keys.

## Method 1 — OAuth 2.1 with dynamic client registration (preferred)

No human has to pre-provision anything for your client. Register yourself, then run
the standard authorization code flow with PKCE. The user approves the grant in their
browser and you receive tokens scoped to the account they choose.

### 1. Register a client (RFC 7591)

```bash
curl -X POST https://crevio.co/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Your Agent",
    "redirect_uris": ["https://your-agent.example/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'
```

The response contains `client_id` and `client_secret`. Store the secret securely —
it is not retrievable later.

### 2. Send the user to authorize

```
https://crevio.co/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-agent.example/callback
  &scope=read_write
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
  &state=RANDOM
```

### 3. Exchange the code for tokens

```bash
curl -X POST https://crevio.co/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://your-agent.example/callback \
  -d code_verifier=YOUR_VERIFIER
```

### Scopes

| Scope | Grants |
| ----- | ------ |
| `read_only` | Read every resource on the account |
| `read_write` | Read and mutate every resource on the account |
| `mcp` | Tool access through the MCP server |

### Identity and credentials

- **Identity types supported:** `anonymous` — clients self-register and are
  identified by the `client_id` they receive. Crevio does not currently accept
  ID-JAG assertions or verified-email agent identities.
- **Credential types supported:** `client_secret_basic`, `client_secret_post`.
- **Revocation:** `POST https://crevio.co/oauth/revoke` with the token to revoke.
  Users can also revoke any client from Settings → Developer.

## Method 2 — Account API key

If a human is available to provision access once, an account owner creates a key at
**Settings → Developer → New API key**. Keys look like `crv_live_...`, are scoped to
a single account, and act on behalf of the user who created them.

```bash
curl https://api.crevio.co/v1/status \
  -H "Authorization: Bearer crv_live_..."
```

Manage keys programmatically once you hold one:

```
GET    /v1/auth/keys      # list (masked)
POST   /v1/auth/keys      # create (secret revealed once)
DELETE /v1/auth/keys/:id  # revoke immediately
```

## Verifying you are authenticated

```bash
curl https://api.crevio.co/health           # liveness, no auth
curl https://api.crevio.co/v1/status \      # confirms which account the token resolves to
  -H "Authorization: Bearer YOUR_TOKEN"
```

A `401` with a `WWW-Authenticate` header carrying `resource_metadata` means your
token is missing, expired, or issued for a different resource — follow that URL to
re-discover the right authorization server.

## Verifying a request that came *from* Crevio

Crevio signs the requests it makes to other sites — link previews, remote media
imports, deployed-site health checks — with Web Bot Auth
([draft-meunier-web-bot-auth-architecture](https://datatracker.ietf.org/wg/webbotauth/about/)),
so you can tell a real Crevio fetch from anything imitating our User-Agent.

A signed request carries three headers:

```
Signature-Agent: "https://crevio.co"
Signature-Input: sig1=("@authority" "signature-agent");created=1755820800
  ;expires=1755821100;keyid="<jwk-thumbprint>";alg="ed25519"
  ;nonce="<random>";tag="web-bot-auth"
Signature: sig1=:<base64-ed25519-signature>:
```

To verify one:

1. Fetch `https://crevio.co/.well-known/http-message-signatures-directory`. It
   returns a JWKS (`application/http-message-signatures-directory+json`) of
   Ed25519 keys, each `kid` being its own RFC 8037 thumbprint and carrying an
   `nbf`/`exp` validity window — refetch once `exp` passes rather than pinning a
   key forever. The directory response is itself signed over `("@authority";req)`
   with tag `http-message-signatures-directory`.
2. Select the key whose thumbprint matches `keyid`.
3. Rebuild the RFC 9421 signature base and check it against `Signature`:

   ```
   "@authority": your-site.example
   "signature-agent": "https://crevio.co"
   "@signature-params": <everything after `sig1=` in Signature-Input>
   ```

4. Reject the request if `created` is in the future or `expires` has passed.

Cloudflare, AWS WAF Bot Control and Fingerprint verify this automatically — no
work needed if you sit behind one of them.

## Next steps

- Capability map: `https://api.crevio.co/skill.md`
- Onboarding walkthrough: `https://api.crevio.co/register.md`
- Full documentation: `https://crevio.co/docs/developer`