# auth.md — Agent Authentication & Registration Protocol

> Canonical: https://www.tac-ghafranchocentral.org/auth.md  
> Organization: The Apostolic Church-Ghana | Afrancho Central Assembly  
> Last Updated: 2026-08-22

This document defines how autonomous AI agents discover, register, authenticate, and interact with The Apostolic Church-Ghana | Afrancho Central Assembly API.

- **Resource Server (API base):** `https://www.tac-ghafranchocentral.org`
- **Authorization Server:** `https://www.tac-ghafranchocentral.org`
- **PRM Discovery:** `https://www.tac-ghafranchocentral.org/.well-known/oauth-protected-resource`
- **Authorization Metadata:** `https://www.tac-ghafranchocentral.org/.well-known/oauth-authorization-server`

---

## 1. Discover

Agents should perform two-hop discovery to identify supported endpoints, flows, and capabilities.

### Protected Resource Metadata (PRM)
Inspect `WWW-Authenticate` on a `401 Unauthorized` response or fetch directly from:
`https://www.tac-ghafranchocentral.org/.well-known/oauth-protected-resource`

```json
{
  "resource": "https://www.tac-ghafranchocentral.org",
  "resource_name": "The Apostolic Church-Ghana | Afrancho Central Assembly",
  "authorization_servers": [
    "https://www.tac-ghafranchocentral.org"
  ],
  "scopes_supported": [
    "public:read",
    "devotionals:read",
    "sermons:read",
    "prayer:submit",
    "newsletter:subscribe"
  ],
  "bearer_methods_supported": [
    "header"
  ]
}
```

### Authorization Server Metadata
Fetch metadata from `https://www.tac-ghafranchocentral.org/.well-known/oauth-authorization-server`:

```json
{
  "issuer": "https://www.tac-ghafranchocentral.org",
  "token_endpoint": "https://www.tac-ghafranchocentral.org/api/oauth2/token",
  "revocation_endpoint": "https://www.tac-ghafranchocentral.org/api/oauth2/revoke",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "urn:workos:agent-auth:grant-type:claim"
  ],
  "agent_auth": {
    "skill": "https://www.tac-ghafranchocentral.org/auth.md",
    "register_uri": "https://www.tac-ghafranchocentral.org/api/agent/identity",
    "identity_types_supported": [
      "anonymous",
      "identity_assertion"
    ],
    "anonymous": {
      "credential_types_supported": ["bearer_token"]
    },
    "identity_assertion": {
      "assertion_types_supported": ["urn:ietf:params:oauth:token-type:jwt"],
      "credential_types_supported": ["bearer_token"]
    }
  }
}
```

---

## 2. Pick a Method

Choose the registration method matching what you have available:

1. **`identity_assertion`** — If you possess a user-delegated ID token/assertion bound to this audience. Completes immediately.
2. **`anonymous`** — If you have neither. Allows immediate execution under `pre_claim_scopes` with deferred claiming.

---

## 3. Register

Register your agent session by sending a request to the identity endpoint:

```http
POST /api/agent/identity HTTP/1.1
Host: www.tac-ghafranchocentral.org
Content-Type: application/json

{
  "type": "anonymous",
  "client_id": "urn:agent:open-assistant"
}
```

---

## 4. Claim Ceremony

When elevating an anonymous session or completing a `service_auth` registration:

### 4a. Get Ceremony Materials
```http
POST /api/agent/identity/claim HTTP/1.1
Host: www.tac-ghafranchocentral.org
Content-Type: application/json

{
  "claim_token": "clm_tacgh_987654321",
  "email": "member@example.com"
}
```

### 4b. Hand off to the User
Prompt the user to confirm:
- **Verification URL:** `https://www.tac-ghafranchocentral.org/visit`
- **User Code:** `TAC-4892`

### 4c. Poll for Completion
```http
POST /api/oauth2/token HTTP/1.1
Host: www.tac-ghafranchocentral.org
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=clm_tacgh_987654321
```

---

## 5. Exchange the Assertion (RFC 7523)

Exchange the `identity_assertion` at `/api/oauth2/token` for a scoped access token:

```http
POST /api/oauth2/token HTTP/1.1
Host: www.tac-ghafranchocentral.org
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhbGciOiJSUzI1Ni...
```

---

## 6. Use the access_token

Include the access token in all API requests via the `Authorization` header:

```http
GET /api/announcements HTTP/1.1
Host: www.tac-ghafranchocentral.org
Authorization: Bearer tac_acc_abcdef123456
```

---

## 7. Errors Reference

| Error Code | Endpoint | Description & Agent Recovery |
| :--- | :--- | :--- |
| `invalid_issuer` | `/api/agent/identity` | Assertion issuer is not trusted. Use `anonymous`. |
| `expired` | `/api/agent/identity` | Client assertion expired. Re-mint assertion and retry. |
| `interaction_required` | `/api/agent/identity` | First-link step-up needed. Execute claim ceremony. |
| `authorization_pending` | `/api/oauth2/token` | User has not yet verified the code. Continue polling. |
| `expired_token` | `/api/oauth2/token` | Claim token expired. Request a new claim attempt. |
| `invalid_grant` | `/api/oauth2/token` | Assertion expired or revoked. Restart from registration. |

---

## 8. Revocation

- **Credential Revocation (RFC 7009):** POST access token to `/api/oauth2/revoke` to invalidate it immediately.
- **Security Event Tokens (RFC 8935):** Security events sent to `/api/agent/events` immediately terminate derived access tokens.