# auth.md

You are an agent that wants to use **vinsocci.com** machine-readable resources (profile, insights, llms.txt, MCP tools).

## Audience

AI agents and automated clients integrating with Vincent Socci's public personal site — not a multi-tenant SaaS. Content and discovery APIs are **public read-only**.

## Discovery

1. Protected Resource Metadata: https://vinsocci.com/.well-known/oauth-protected-resource
2. Authorization Server Metadata: https://vinsocci.com/.well-known/oauth-authorization-server
3. API catalog: https://vinsocci.com/.well-known/api-catalog
4. OpenAPI: https://vinsocci.com/openapi.json
5. MCP server card: https://vinsocci.com/.well-known/mcp/server-card.json

## Authentication model

**Unauthenticated GET is sufficient** for every public discovery endpoint. Bearer tokens are optional and only advertise `public:read`.

| Resource | URL | Auth |
| --- | --- | --- |
| Profile JSON | https://vinsocci.com/api/v1/profile | none |
| Insights JSON | https://vinsocci.com/api/v1/insights | none |
| Health | https://vinsocci.com/api/v1/health | none |
| llms.txt | https://vinsocci.com/llms.txt | none |
| MCP tools | https://vinsocci.com/mcp | none |

## Supported registration method: anonymous

Use this when your runtime wants a token anyway (shared OAuth client code paths).

### register_uri

`POST https://vinsocci.com/agent/register`

No body required. Response:

```json
{
  "access_token": "vs_public_…",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "public:read"
}
```

### identity_endpoint (optional)

`POST https://vinsocci.com/agent/identity`

```json
{ "type": "anonymous" }
```

Returns an `identity_assertion` and `claim_token`. Claiming is **not required** for public:read.

### token_endpoint

`POST https://vinsocci.com/oauth/token`

Accepts `client_credentials` or JWT-bearer style grants and returns a `public:read` bearer.

### claim_uri

`POST https://vinsocci.com/agent/identity/claim` — responds that claim is not required for this site.

## Credential use

If you hold a bearer token, send:

`Authorization: Bearer <access_token>`

Do not print tokens in logs. Tokens are opaque and site-issued; JWKS is empty because tokens are not JWTs.

## Content usage

robots.txt Content Signals: `ai-train=yes, search=yes, ai-input=yes`.

## Developer portal

Human and agent documentation, sandbox, CLI, rate limits, and versioning: https://vinsocci.com/developers

Self-serve optional key: POST https://vinsocci.com/agent/register (free public tier; GET works with no token).

## Human contact

Professional inquiries: https://vinsocci.com/contact (HTML form). Not an agent registration path.

## What is not supported

- User account creation / multi-tenant app registration
- ID-JAG `identity_assertion` from third-party providers
- Verified-email claim ceremonies for elevated scopes
- Write APIs

When elevated or write APIs appear, this file and the OAuth metadata will be updated first.