# auth.md - ArtoLeaf Agent Authentication & Registration

You are an AI agent. ArtoLeaf supports **agentic registration**: discovery → registration → (optional claim) → token exchange → authenticated API usage → revocation handling.

## Discovery Endpoints

- **Protected Resource Metadata (RFC 9728)**: `https://artoleaf.com/.well-known/oauth-protected-resource`
- **OAuth 2.0 Authorization Server (RFC 8414)**: `https://artoleaf.com/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery 1.0**: `https://artoleaf.com/.well-known/openid-configuration`
- **JSON Web Key Set (JWKS)**: `https://artoleaf.com/.well-known/jwks.json`
- **API Catalog (RFC 9727)**: `https://artoleaf.com/.well-known/api-catalog`
- **OpenAPI 3.1 Specification**: `https://artoleaf.com/api/openapi.json`

---

## Step 1 — Discovery

When accessing protected endpoints without credentials, responses contain a 401 status with the PRM discovery header:
```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://artoleaf.com/.well-known/oauth-protected-resource"
```

Fetch Protected Resource Metadata:
```http
GET https://artoleaf.com/.well-known/oauth-protected-resource
```

Fetch Authorization Server Metadata:
```http
GET https://artoleaf.com/.well-known/oauth-authorization-server
```

---

## Step 2 — Choose Identity & Registration Method

ArtoLeaf supports three agent registration methods:

1. **Identity Assertion (ID-JAG)**: When acting on behalf of an authenticated user via a trusted Identity Provider.
   - Assertion Type: `urn:ietf:params:oauth:token-type:id-jag`
   - Credential Type: `bearer_token`
2. **Verified Email**: When you possess verified email identity claims for the user.
   - Assertion Type: `verified_email`
   - Claim Ceremony: `https://artoleaf.com/agent/claim`
3. **Anonymous Agent**: For guest / unauthenticated agent browsing or catalog queries.
   - Method: `anonymous`
   - Claim Ceremony: Optional delegation to user account later via `https://artoleaf.com/agent/claim`.

---

## Step 3 — Agent Registration

Submit an identity registration request to the authorization server:
```http
POST https://artoleaf.com/agent/identity
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<signed_id_jag_jwt>",
  "client_name": "ArtoLeaf AI Shopping Assistant"
}
```

For anonymous sessions:
```http
POST https://artoleaf.com/agent/identity
Content-Type: application/json

{
  "identity_type": "anonymous",
  "client_name": "Autonomous Agent"
}
```

---

## Step 4 — Token Exchange

Exchange your registered assertion at the OAuth token endpoint:
```http
POST https://artoleaf.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<service_signed_identity_assertion>&client_id=agent
```

Response:
```json
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email api:read api:write"
}
```

---

## Step 5 — Authenticated API Calls

Include the token in HTTP requests via standard Authorization header:
```http
GET https://artoleaf.com/api/products
Authorization: Bearer <access_token>
```

---

## Step 6 — Revocation & Lifecycle

To revoke an issued token:
```http
POST https://artoleaf.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token
```

Revocation events are delivered per RFC 8935 via the Security Event Token schema:
`https://schemas.workos.com/events/agent/auth/identity/assertion/revoked`.