# auth.md

You are an agent. This service supports **agentic registration**: discover → register → (claim if needed) → exchange for an access_token → call API → handle revocation. Follow the steps in order; do not skip ahead.

Hosts: `https://intelasolution.com` (resource and authorization server).

## Step 1 — Discover

Discovery is two hops.

The 401 response carries a `WWW-Authenticate` header pointing to Protected Resource Metadata:
```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://intelasolution.com/.well-known/oauth-protected-resource"
```

### 1a. Fetch the Protected Resource Metadata
```http
GET https://intelasolution.com/.well-known/oauth-protected-resource
```
Response contains:
- `resource`: `https://intelasolution.com`
- `authorization_servers`: `["https://intelasolution.com"]`
- `scopes_supported`: `["read:services", "read:products", "read:insights", "submit:enquiry"]`
- `bearer_methods_supported`: `["header"]`

### 1b. Fetch the Authorization Server metadata
```http
GET https://intelasolution.com/.well-known/oauth-authorization-server
```
Response contains the `agent_auth` block:
- `identity_endpoint`: `https://intelasolution.com/api/auth/register`
- `claim_endpoint`: `https://intelasolution.com/api/auth/claim`
- `token_endpoint`: `https://intelasolution.com/api/auth/token`
- `revocation_endpoint`: `https://intelasolution.com/api/auth/revoke`

## Step 2 — Pick a method

Use this decision tree:
1. **You have a session tied to a user identity and can exchange it for an ID-JAG** → `identity_assertion + id-jag`.
2. **You have only the user's email** → `service_auth`. Claim ceremony required.
3. **You have neither** → `anonymous`. Claim ceremony optional.

## Step 3 — Register

POST to the `identity_endpoint`:
```http
POST https://intelasolution.com/api/auth/register
Content-Type: application/json
```

### identity_assertion + id-jag
Mint the assertion with:
- `aud`: `https://intelasolution.com`
- `iss`: your provider issuer URL
- `assertion_type`: `urn:ietf:params:oauth:token-type:id-jag`

Send:
```json
{
  "method": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<base64url-id-jag>"
}
```

### service_auth
Send:
```json
{
  "method": "service_auth",
  "email": "user@example.com"
}
```

### anonymous
Send:
```json
{
  "method": "anonymous"
}
```

## Step 4 — Claim (if needed)

If performing `service_auth` or claiming an `anonymous` registration, direct the user to verify:
- POST claim code to `https://intelasolution.com/api/auth/claim`
- Verification URL: `https://intelasolution.com/claim?code={code}`

## Step 5 — Exchange for access_token

Exchange your verified assertion for an access token:
```http
POST https://intelasolution.com/api/auth/token
Content-Type: application/x-www-form-urlencoded

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

Response:
```json
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:services read:products read:insights submit:enquiry"
}
```

## Step 6 — Call the API

Send requests with the Bearer token:
```http
GET /api/products HTTP/1.1
Host: intelasolution.com
Authorization: Bearer <access_token>
```

Public read-only endpoints do not require authentication:
- `GET /api/products` (Enterprise product catalog)
- `GET /api/insights` (Published articles)
- `GET /api/industries` (Enterprise industry solutions)
- `GET /llms.txt` and `GET /llms-full.txt` (Structured LLM text)

## Step 7 — Handle Revocation

When revoking access:
```http
POST https://intelasolution.com/api/auth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token>
```