# Rift Rigs auth.md

You are an automated AI agent or agent provider interacting with Rift Rigs. This service implements **agentic registration** (Auth.md) so autonomous agents can discover authentication requirements, self-register, obtain scoped credentials, and call protected APIs.

- **Audience**: AI Agents, LLM tool executors, autonomous agents acting on behalf of users or automated services.
- **Resource Identifier**: `https://riftrigs.com`
- **Authorization Server**: `https://riftrigs.com`
- **API Documentation**: `https://riftrigs.com/docs/api`
- **OpenAPI Specification**: `https://riftrigs.com/docs/openapi.json`
- **API Catalog**: `https://riftrigs.com/.well-known/api-catalog`

---

## 1. Discovery

Before registering or requesting credentials, fetch the discovery documents:

1. **OAuth Protected Resource Metadata (RFC 9728)**:
   ```http
   GET /.well-known/oauth-protected-resource HTTP/1.1
   Host: riftrigs.com
   Accept: application/json
   ```
   Returns `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`.

2. **OAuth Authorization Server Metadata (RFC 8414 & Auth.md)**:
   ```http
   GET /.well-known/oauth-authorization-server HTTP/1.1
   Host: riftrigs.com
   Accept: application/json
   ```
   Contains the `agent_auth` extension block specifying endpoints and supported identity/credential types.

---

## 2. Endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/.well-known/oauth-protected-resource` | GET | Protected resource metadata (RFC 9728) |
| `/.well-known/oauth-authorization-server` | GET | Authorization server discovery with `agent_auth` block |
| `/agent/auth/register` | POST | Agent registration / identity assertion endpoint |
| `/agent/auth/claim` | POST | Out-of-band user claim initiation endpoint |
| `/oauth/token` | POST | Token exchange (JWT-bearer and claim grants) |
| `/oauth/revoke` | POST | Token revocation (RFC 7009) |
| `/agent/auth/revoke` | POST | Agent registration revocation endpoint |

---

## 3. Supported Registration Flows

Rift Rigs supports three registration mechanisms:

### Flow A: Identity Assertion (ID-JAG)
For agents whose provider mints Identity Assertions using ID-JAG ([draft-ietf-oauth-identity-assertion-authz-grant]):
1. Obtain an ID-JAG token from your agent provider with audience `https://riftrigs.com`.
2. Submit assertion to `POST /agent/auth/register`:
   ```json
   {
     "type": "identity_assertion",
     "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
     "assertion": "<id_jag_jwt>"
   }
   ```
3. Exchange the returned assertion at `POST /oauth/token` via `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` for a bearer access token.

### Flow B: Verified-Email Identity Assertion
For agents registering on behalf of a verified email address:
1. Submit the email to `POST /agent/auth/register`:
   ```json
   {
     "type": "service_auth",
     "login_hint": "user@example.com"
   }
   ```
2. The user receives a verification code and link (`https://riftrigs.com/agent/claim?code=...`).
3. Poll `POST /oauth/token` with `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=...` until authorization is granted.

### Flow C: Anonymous Registration with Claim Ceremony
For autonomous agents that operate anonymously first and optionally claim user ownership later:
1. Self-register at `POST /agent/auth/register`:
   ```json
   {
     "type": "anonymous"
   }
   ```
2. Receive a temporary scoped `identity_assertion` and `claim_token`.
3. Exchange at `POST /oauth/token` for an immediate restricted `access_token`.
4. When a user wishes to claim this agent session, initiate claim via `POST /agent/auth/claim` with `claim_token`.

---

## 4. Scopes & Supported Credentials

### Supported Scopes
- `api:read`: Read-only access to catalog, products, benchmarks, and compatibility data.
- `api:write`: Create custom PC configurations, cart sessions, and orders.
- `builder:read`: Query PC component compatibility matrix and wattage calculations.
- `builder:write`: Save, validate, and update PC builds.
- `openid`, `profile`, `email`: Standard identity claims.

### Credential Usage
Include the issued access token in standard HTTP Authorization headers:
```http
Authorization: Bearer <access_token>
```

---

## 5. Revocation

- **Token Revocation (RFC 7009)**:
  `POST /oauth/revoke` with form data `token=<access_token>&token_type_hint=access_token`.
- **Agent Identity Revocation**:
  `POST /agent/auth/revoke` to invalidate all active credentials associated with the agent identity.