# auth.md

You are an agent. Arcane Fortress supports agent registration for customer-scoped commerce. Discover the metadata first, then register only when you need a shopper identity. Do not skip discovery.

## Audience

- Public catalog, Markdown twins, `/llms.txt`, and UCP discovery: no credential.
- Customer account, Customer Account API, and UCP checkout: `identity_assertion` with `verified_email`, then an OAuth `access_token`.

This service does not issue anonymous API keys and does not accept ID-JAGs.

## Step 1 — Discover

Fetch Protected Resource Metadata from this origin:

```http
GET /.well-known/oauth-protected-resource
```

Document: https://arcane-fortress.com/.well-known/oauth-protected-resource

Read `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`.

`authorization_servers[0]` is `https://arcane-fortress.com` — this origin. It is the authorization server that implements the `agent_auth` profile, so fetch its metadata next. The `agent_auth` block lives here:

```http
GET /.well-known/oauth-authorization-server
```

Document: https://arcane-fortress.com/.well-known/oauth-authorization-server

Its `issuer` is `https://arcane-fortress.com`, matching `authorization_servers[0]`. Read `agent_auth.skill`, `register_uri`, `identity_types_supported`, credential types, and the claim/revocation URLs:

```json
{
  "agent_auth": {
    "skill": "https://arcane-fortress.com/auth.md",
    "register_uri": "https://arcane-fortress.com/account/register",
    "identity_endpoint": "https://arcane-fortress.com/account/register",
    "claim_uri": "https://arcane-fortress.com/account/login",
    "claim_endpoint": "https://arcane-fortress.com/account/login",
    "revocation_uri": "https://arcane-fortress.com/account/logout",
    "identity_types_supported": [
      "identity_assertion"
    ],
    "identity_assertion": {
      "assertion_types_supported": [
        "verified_email"
      ],
      "credential_types_supported": [
        "access_token"
      ]
    }
  }
}
```

`authorization_servers[1]` is `https://shopify.com/authentication/76504039747` — Shopify Customer Accounts, the upstream issuer that mints access tokens. Registration, claim, and revocation happen on this origin; token issuance is delegated there. Its OpenID Provider metadata is mirrored at https://arcane-fortress.com/.well-known/openid-configuration, and `iss` in an issued ID token is `https://shopify.com/authentication/76504039747`, not this origin.

## Step 2 — Pick a method

1. Catalog, collections, pages, journal, and policy Markdown: stop. No registration.
2. You need a shopper identity for account or checkout: `identity_assertion` with `verified_email`.

Before asserting a user's email, show them the service name (`Arcane Fortress`) and the scopes you will request.

## Step 3 — Register

Direct the user to `register_uri`:

https://arcane-fortress.com/account/register

The user creates a customer with a verified email and password. Shopify may send an activation message. Do not invent accounts, emails, or passwords. HTML form registration is the supported method; do not POST JSON to this URL.

## Step 4 — Claim / sign in

After the customer exists, complete the claim at `claim_uri` so the user proves control of the email:

https://arcane-fortress.com/account/login

For Customer Account API and UCP MCP tools, then run OAuth 2.0 authorization code with PKCE:

- Authorize: `https://shopify.com/authentication/76504039747/oauth/authorize`
- Token: `https://shopify.com/authentication/76504039747/oauth/token`
- Request only scopes from `scopes_supported`

## Step 5 — Use the access token

Send the token as a header (`bearer_methods_supported` includes `header`):

```http
Authorization: Bearer <access_token>
```

Commerce tools:

- UCP discovery: https://arcane-fortress.com/.well-known/ucp
- UCP MCP: https://arcane-fortress.com/api/ucp/mcp

Use live catalog Markdown or UCP tools for prices and availability. Do not scrape cart or account HTML.

## Errors

If a previously working token returns `401`, drop it and restart at Step 1. Account pages are HTML forms, not JSON registration APIs. Retry 5xx with backoff. Do not retry the same 4xx payload.

## Revocation

Revoke a storefront session at `revocation_uri`:

https://arcane-fortress.com/account/logout

End Customer Account API sessions at `https://shopify.com/authentication/76504039747/logout`.