# auth.md | ten12group.com

## Audience

This document is for AI agents and automated clients integrating with the
Ten Twelve Design Group Inc. public API at `https://ten12group.com`.

## Public content

All pages, project data, llms.txt, llms-full.txt and machine-readable
metadata at this origin are **public**. No authentication, registration or
API key is required to read them.

## API surface

Versioned public API under `/api/v1/`:

- `GET /api/v1`: API index (version, endpoints, deprecation policy).
- `GET /api/v1/projects`: portfolio projects.
- `GET /api/v1/services`: service catalog.
- `POST /api/v1/contact`: project inquiry endpoint. `POST /api/contact` is
  a deprecated alias and sends `Deprecation`/`Sunset` headers.
- Content types: `application/json` or `application/x-www-form-urlencoded`.
- Required inquiry fields: `name`, `email`, `message`, `location`, `budget`, `phase`.
- Optional field: `phone`.
- Errors return JSON: `{ "ok": false, "error", "code", "hint" }`.
- MCP server: `POST /mcp` (Streamable HTTP JSON-RPC): tools
  `list_projects`, `list_services`, `submit_inquiry`. Server card:
  https://ten12group.com/.well-known/mcp/server-card.json
- Developer portal: https://ten12group.com/developers
- Machine-readable contract: https://ten12group.com/openapi.json

## Agent registration (self-serve, no approval)

A self-hosted OAuth 2.0 authorization server runs at this origin. Agents may
register themselves and obtain `client_credentials` access tokens. No human
approval, no API key request, no account creation.

1. **Register**: `POST https://ten12group.com/oauth/register` (RFC 7591)

   ```sh
   curl -X POST https://ten12group.com/oauth/register \
     -H 'Content-Type: application/json' \
     -d '{"client_name": "my-agent", "grant_types": ["client_credentials"]}'
   ```

   Response: `client_id`, `client_secret` (shown once. Store it securely).

2. **Get a token**: `POST https://ten12group.com/oauth/token`
   (`grant_type=client_credentials`)

   ```sh
   curl -X POST https://ten12group.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=client_credentials
   ```

   Response: `access_token` (EdDSA JWT, `iss=https://ten12group.com`,
   1-hour TTL), `token_type`, `expires_in`, `scope`.

3. **Use the token**: send `Authorization: Bearer <token>` on API calls.
   Tokens are optional: unauthenticated calls still work. A bad or expired
   Bearer token returns `401` with a `WWW-Authenticate` challenge.

4. **Validate / revoke**: `POST /oauth/introspect` (RFC 7662) and
   `POST /oauth/revoke` (RFC 7009), authenticated with client credentials.

### Discovery documents

- Authorization server metadata (RFC 8414, includes `agent_auth`):
  https://ten12group.com/.well-known/oauth-authorization-server
- Protected-resource metadata (RFC 9728):
  https://ten12group.com/.well-known/oauth-protected-resource
- JWKS (Ed25519 public key): https://ten12group.com/oauth/jwks.json
- Identity model: anonymous client credentials (`identity_types_supported:
  ["anonymous"]` in `agent_auth`).

## Rate limits

Advertised via `RateLimit-Limit` / `RateLimit-Remaining` /
`RateLimit-Reset` / `RateLimit-Policy` response headers; a 429 includes
`Retry-After`. Inquiries: 5 per 15 minutes per client IP. Reads: 60 per
minute per client IP. Registration: 5 per 15 minutes. Token: 30 per minute.

## Contact for agents

If an agent integration needs a capability beyond this surface, email
info@ten12group.com.