# Auth — V-Sum

## Overview

V-Sum is a curated finance media and convening company. All public content (briefings, events, companies, people, interviews) is freely accessible without authentication. Operator APIs require Google OAuth.

## Discover

Agents discover V-Sum's auth requirements through standard metadata endpoints:

```http
GET https://v-sum.com/.well-known/oauth-protected-resource HTTP/1.1
Accept: application/json
Host: v-sum.com
```

Returns RFC 9728 Protected Resource Metadata including `authorization_servers` and `scopes_supported`.

```http
GET https://v-sum.com/.well-known/oauth-authorization-server HTTP/1.1
Accept: application/json
Host: v-sum.com
```

Returns RFC 8414 Authorization Server Metadata with `authorization_endpoint`, `token_endpoint`, and the `agent_auth` block indicating public API and MCP require no auth.

```http
GET https://v-sum.com/.well-known/openid-configuration HTTP/1.1
Accept: application/json
Host: v-sum.com
```

Returns OpenID Connect Discovery metadata.

Unauthenticated requests to protected endpoints return 401 with a discovery hint:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://v-sum.com/.well-known/oauth-protected-resource"
Content-Type: application/json

{"error": "Unauthorized"}
```

## Register

### Public access (no registration required)

All read endpoints work immediately without any registration or credentials:

```http
GET https://api.v-sum.com/briefings HTTP/1.1
Accept: application/json
```

```http
POST https://v-sum.com/mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"agent","version":"1.0"}}}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": {"name": "v-sum", "version": "1.42.0"},
    "capabilities": {"tools": {"listChanged": false}, "resources": {"subscribe": false}}
  }
}
```

### Operator access (Google OAuth)

Staff members authenticate via Google OAuth. The flow:

1. Redirect to `https://accounts.google.com/o/oauth2/v2/auth` with `scope=openid email profile`
2. Exchange the authorization code at `https://oauth2.googleapis.com/token`
3. A session cookie (`__Host-vsum_session`) is set for subsequent requests

There is no self-service API key product. Operator access is limited to staff.

## Use credential

### Public endpoints (no credential)

Public API and MCP requests need no Authorization header:

```http
GET https://api.v-sum.com/events HTTP/1.1
Accept: application/json
```

```http
GET https://api.v-sum.com/briefings/v-sardine HTTP/1.1
Accept: application/json
```

### Operator endpoints (session cookie)

Authenticated requests carry the session cookie set after OAuth:

```http
GET https://v-sum.com/api/admin/events HTTP/1.1
Cookie: __Host-vsum_session=<session_token>
Accept: application/json
```

## Errors

| Error Code | HTTP Status | Description |
|---|---|---|
| `unauthorized` | 401 | No valid session. Retry after authenticating via Google OAuth. |
| `forbidden` | 403 | Valid session but insufficient role (admin required). |
| `not_found` | 404 | No API route exists at this path. |
| `rate_limited` | 429 | Too many requests. Retry after the `Retry-After` header value (seconds). |
| `credential_expired` | 401 | Session cookie expired. Re-authenticate via Google OAuth. |
| `invalid_claim_token` | 401 | Session token is malformed or was revoked. |
| `claim_expired` | 401 | The OAuth claim has expired. Re-initiate the OAuth flow. |
| `service_unavailable` | 503 | Database unavailable. Retry with exponential backoff. |

All error responses are JSON:

```json
{"error": "rate_limited", "message": "Too many requests", "retry_after": 60}
```

## Scopes

| Scope | Auth Required | Description |
|---|---|---|
| `briefings:read` | No | Read briefing metadata, chapters, video refs |
| `events:read` | No | Read event metadata and briefing lists |
| `companies:read` | No | Read company profiles and briefing history |
| `people:read` | No | Read presenter profiles and appearances |
| `interviews:read` | No | Read published interviews |
| `briefings:write` | Yes (staff) | Create/update briefing records |
| `events:write` | Yes (staff) | Create/update event records |

## Rate Limits

| Endpoint Pattern | Window | Max Requests |
|---|---|---|
| Public API list endpoints | 60s | 60 |
| Public API detail endpoints | 60s | 120 |
| Registration endpoints | 3600s | 10 |
| Auth endpoints | 300s | 10 |

## SDKs

- npm: `npm install v-sum` (or `vsum-api-client`)
- PyPI: `pip install vsum-api-client`
- Go: `go get github.com/superduperdot/vsum-sdk-go`

## Discovery Metadata

- Authorization Server (RFC 8414): `https://v-sum.com/.well-known/oauth-authorization-server`
- Protected Resource (RFC 9728): `https://v-sum.com/.well-known/oauth-protected-resource`
- OpenID Configuration: `https://v-sum.com/.well-known/openid-configuration`
- Agent Permissions: `https://v-sum.com/.well-known/agent-permissions.json`
- Agent Capability Manifest: `https://v-sum.com/agents.json`
- Pricing: `https://v-sum.com/pricing.md`

## Contact

For API access questions: hello@v-sum.com