# auth.md

Culture Vault agent registration for Culture Vault Apparel & Clothing. Resource server and authorization server: https://culturevolt.tmctechsolutions.com.

Agents may register shoppers for a customer account (email + password, then a 6-digit claim code). Guest checkout never needs an account.

## 1. Discover

On `401 Unauthorized`, read `WWW-Authenticate: Bearer resource_metadata="…"`. Otherwise fetch:

- Protected resource: https://culturevolt.tmctechsolutions.com/.well-known/oauth-protected-resource
- Authorization server: https://culturevolt.tmctechsolutions.com/.well-known/oauth-authorization-server

PRM fields: `resource`, `resource_name`, `authorization_servers`, `scopes_supported`, `bearer_methods_supported`, `issuer`.

AS fields: `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`, and the `agent_auth` block (`skill`, `register_uri`, `identity_endpoint`, `claim_endpoint`, `identity_types_supported`, `anonymous`, `identity_assertion`, `revocation_uri`).

## agent_auth

```json
{
  "skill": "https://culturevolt.tmctechsolutions.com/auth.md",
  "register_uri": "https://culturevolt.tmctechsolutions.com/api/auth/register",
  "identity_endpoint": "https://culturevolt.tmctechsolutions.com/api/agent/auth",
  "claim_endpoint": "https://culturevolt.tmctechsolutions.com/api/agent/auth/claim",
  "claim_uri": "https://culturevolt.tmctechsolutions.com/api/agent/auth/claim",
  "events_endpoint": "https://culturevolt.tmctechsolutions.com/api/oauth/revoke",
  "revocation_uri": "https://culturevolt.tmctechsolutions.com/api/oauth/revoke",
  "identity_types_supported": [
    "anonymous",
    "identity_assertion"
  ],
  "anonymous": {
    "credential_types_supported": [
      "opaque_token"
    ],
    "claim_uri": "https://culturevolt.tmctechsolutions.com/api/oauth/token",
    "register_uri": "https://culturevolt.tmctechsolutions.com/api/agent/auth"
  },
  "identity_assertion": {
    "assertion_types_supported": [
      "verified_email"
    ],
    "credential_types_supported": [
      "password",
      "opaque_token"
    ],
    "claim_uri": "https://culturevolt.tmctechsolutions.com/api/agent/auth/claim",
    "register_uri": "https://culturevolt.tmctechsolutions.com/api/auth/register"
  },
  "events_supported": [
    "https://schemas.openid.net/secevent/oauth/event-type/token-revoked",
    "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
  ]
}
```

## 2. Pick a method

- No user identity → `anonymous` (public catalog token).
- User email for a Culture Vault customer account → `identity_assertion` / `verified_email` (register, then claim with the 6-digit code).
- ID-JAG from a trusted provider → `identity_assertion` with `urn:ietf:params:oauth:token-type:id-jag` (not enabled yet; use verified email).

## 3. Register

### anonymous

POST `https://culturevolt.tmctechsolutions.com/api/auth/register`

```http
POST /api/auth/register HTTP/1.1
Host: culturevolt.tmctechsolutions.com
Content-Type: application/json
```

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

### identity_assertion (verified_email) — customer sign-up

POST `https://culturevolt.tmctechsolutions.com/api/auth/register`

```json
{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "name": "Agent Shopper",
  "email": "shopper@example.com",
  "password": "at-least-8-chars",
  "newsletter": false
}
```

Humans use the same endpoint from https://culturevolt.tmctechsolutions.com/account (name, email, password). The account stays unverified until the shopper opens the email link or enters the 6-digit code.

## 4. Claim ceremony

The service emails a 6-digit `user_code`. The shopper signs in at https://culturevolt.tmctechsolutions.com/account/verify and types the code — do not send the code back to the agent.

POST `https://culturevolt.tmctechsolutions.com/api/agent/auth/claim`

```json
{ "email": "shopper@example.com", "code": "123456" }
```

## 5. Token

POST `https://culturevolt.tmctechsolutions.com/api/oauth/token`

Password grant (verified customer APIs only):

```
grant_type=password
username=shopper@example.com
password=at-least-8-chars
scope=account bag orders
```

Client credentials (public catalog):

```
grant_type=client_credentials
scope=catalog:read
```

Send `Authorization: Bearer {access_token}` on `/api/account/*`.

## Scopes

- `catalog:read` — public catalogue and search
- `account` — profile
- `bag` — saved bag and wishlist
- `orders` — order history

## Public APIs (no token)

- https://culturevolt.tmctechsolutions.com/api/catalog
- https://culturevolt.tmctechsolutions.com/api/search?q=
- https://culturevolt.tmctechsolutions.com/api/health
- https://culturevolt.tmctechsolutions.com/mcp

## Revocation

POST `https://culturevolt.tmctechsolutions.com/api/oauth/revoke` with the access token (RFC 7009).

## Humans

Shoppers create an account at https://culturevolt.tmctechsolutions.com/account. Contact info@tmctechsolutions.com or WhatsApp +263 78 153 3476 if registration email does not arrive.