# TYTEC.ai auth.md

## Discover

TYTEC.ai operates a minimal OAuth 2.0 authorization service for a separate read-only agent resource. It does not implement OpenID Connect.

- Protected Resource Metadata: `https://tytec.ai/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://tytec.ai/.well-known/oauth-authorization-server`
- Protected resource identifier and audience: `https://tytec.ai`

Existing public REST, MCP, and WebMCP discovery remains anonymous.

## Register

Register a restricted anonymous agent client:

```http
POST /agent/identity
Content-Type: application/json

{
	"type": "anonymous",
	"scope": "services:read locations:read coverage:read"
}
```

The response returns a `client_id` and one-time `client_secret`. Store the secret securely. The only supported client authentication method is `client_secret_basic`.

The current auth.md field is `agent_auth.identity_endpoint`. The metadata also publishes `register_uri` as a scanner compatibility alias to the same real endpoint. TYTEC does not currently implement identity assertions, ID-JAG, verified-email registration, claim ceremonies, or security-event delivery, so it does not advertise `claim_endpoint`, `events_endpoint`, or `events_supported`.

## Obtain A Token

Use the OAuth 2.0 client credentials grant:

```http
POST /oauth2/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&resource=https%3A%2F%2Ftytec.ai&scope=services%3Aread
```

Access tokens are opaque Bearer tokens, expire after 900 seconds, are audience-restricted to `https://tytec.ai`, and are accepted only in the `Authorization` header. Tokens and client secrets are not stored in plaintext.

## Scopes And Protected Endpoints

| Scope | Endpoint | Effect |
|---|---|---|
| `services:read` | `GET /api/v1/agent/services` | Read the service catalog |
| `locations:read` | `GET /api/v1/agent/locations` | Read published coverage locations |
| `coverage:read` | `GET /api/v1/agent/coverage?city=Stockholm&country=SE` | Check published city coverage |

No OAuth write scopes exist. In particular, there are no dispatch, order, billing, invoice, quotation-acceptance, infrastructure-write, or administrative scopes.

## Revoke

Revoke an access token using the same client credentials that obtained it:

```http
POST /oauth2/revoke
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN&token_type_hint=access_token
```

Revocation is immediate. Per RFC 7009, the endpoint returns HTTP 200 for a token that is already invalid or unknown when client authentication succeeds.

## Errors

- Missing, malformed, expired, or revoked Bearer tokens return `401` with an RFC 9728 `resource_metadata` discovery hint.
- A valid token missing the required scope returns `403` with `insufficient_scope`.
- Invalid client credentials return `401` with `invalid_client`.
- Unsupported grants, resources, scopes, or identity types return OAuth-style JSON errors.
- Registration, token, and revocation endpoints are rate limited and reject oversized request bodies.

## Safety

OAuth protects only the additive read-only agent resource. Public lead and quote intake remains separate and non-binding. Lead submissions and quote requests require human review; they do not automatically create a billable order, accept a quotation, create an invoice, dispatch an engineer, or perform an infrastructure change.