# Authentication Protocol for AI Agents

Welcome, AI Agent. This document defines the exact protocol for obtaining credentials and accessing protected resources on `https://zainahmed.net` in compliance with the WorkOS `auth.md` specification.

## Discover

Protected resource metadata is published at `https://zainahmed.net/.well-known/oauth-protected-resource` (RFC 9728) and authorization server metadata is located at `https://zainahmed.net/.well-known/oauth-authorization-server` (RFC 8414).

When an unauthenticated agent invokes a protected endpoint without credentials, the server returns an HTTP `401 Unauthorized` response with a spec-shaped `WWW-Authenticate` header:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://zainahmed.net/.well-known/oauth-protected-resource"
```

Agents can read the declaration at `https://zainahmed.net/.well-known/oauth-protected-resource` to discover the `agent_auth` capabilities, `identity_endpoint`, and supported authentication modes.

## Pick a method

Agents may select between two supported identity schemes under the `agent_auth` declaration:

1. **Anonymous Mode (`service_auth`)**: For non-destructive discovery, read-only system queries, and public sandbox execution. No human credentials required.
2. **Identity Assertion Mode (`identity_assertion`)**: For authenticated consultation dispatches, SLA tracking, and webhook subscriptions via verified human delegation or cryptographic identity assertions (`id-jag`).

## Register

To register your agent instance dynamically, send an HTTP POST request to the `register_uri`:

```http
POST https://zainahmed.net/api/v1/agent/register
Content-Type: application/json

{
  "client_name": "Autonomous-Architect-Agent",
  "identity_type": "service_auth",
  "redirect_uris": ["https://zainahmed.net/api/v1/agent/callback"]
}
```

Response:

```json
{
  "client_id": "agent_cl_9831f00a",
  "client_secret": "sec_ephemeral_demo_key",
  "expires_in": 86400
}
```

## Claim

For agents operating with verified human delegation (`identity_assertion`), submit your signed JWT assertion or `id-jag` token to the `claim_uri` (or `identity_endpoint`):

```http
POST https://zainahmed.net/api/v1/agent/claim
Content-Type: application/json

{
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<SIGNED_IDENTITY_ASSERTION_JWT>"
}
```

Response:

```json
{
  "claim_ticket": "clm_live_sec_778129a0f44e",
  "expires_in": 900
}
```

## Exchange

Exchange your claim ticket or dynamic client credentials for an active OAuth 2.0 access token at the token endpoint:

```http
POST https://zainahmed.net/api/v1/agent/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=clm_live_sec_778129a0f44e&
subject_token_type=urn:ietf:params:oauth:token-type:id-jag
```

Response:

```json
{
  "access_token": "za_tok_991823abce",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:profile read:projects read:articles write:contact"
}
```

## Use the access_token

Include the returned token in the HTTP `Authorization` header on all subsequent API requests:

```http
GET https://zainahmed.net/api/v1/projects
Authorization: Bearer za_tok_991823abce
```

Protected endpoints validate the bearer token against the active session cache and grant access based on granted scopes.

## Errors

Standard RFC 6749 and RFC 9457 error responses are returned when authentication or authorization fails:

- `invalid_request` (400): Malformed headers or missing client parameters.
- `invalid_token` (401): Expired or unrecognized bearer token; inspect `WWW-Authenticate` header.
- `insufficient_scope` (403): Token lacks the required permission scope.

Example error payload:

```json
{
  "type": "https://zainahmed.net/docs/errors/invalid-token",
  "title": "Invalid Token",
  "status": 401,
  "detail": "The provided access token has expired or is invalid.",
  "code": "invalid_token"
}
```

## Revocation

To revoke an issued token or terminate an agent session, send a POST request to the `revocation_uri`:

```http
POST https://zainahmed.net/api/v1/agent/revoke
Content-Type: application/x-www-form-urlencoded

token=za_tok_991823abce&token_type_hint=access_token
```

Response: HTTP `200 OK` (or `204 No Content`).