# auth.md — Agent Authentication & Registration

> Specification & Discovery for AI Agent Registration and Automated Authentication

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.

## Step 1 — Discover

Discovery starts with the OAuth Protected Resource Metadata (PRM) and Authorization Server (AS) metadata.

### 1a. Fetch the Protected Resource Metadata (RFC 9728)

```http
GET /.well-known/oauth-protected-resource
```

**Response:**

```json
{
  "resource": "https://arfat.is-a.dev",
  "resource_name": "Momin Mohammed Arfat Portfolio & Developer APIs",
  "resource_documentation": "https://arfat.is-a.dev/auth.md",
  "authorization_servers": ["https://arfat.is-a.dev"],
  "scopes_supported": ["openid", "profile", "email", "read", "write"],
  "bearer_methods_supported": ["header"],
  "jwks_uri": "https://arfat.is-a.dev/.well-known/jwks.json"
}
```

- `resource` — Canonical URL of the API. Use this as `aud` when minting an ID-JAG token.
- `authorization_servers` — Base URLs of the OAuth Authorization Server(s).
- `scopes_supported` — Scopes understood by the service.
- `bearer_methods_supported` — Access token transmission format (`"header"` = `Authorization: Bearer <token>`).

### 1b. Fetch the Authorization Server Metadata (RFC 8414)

```http
GET /.well-known/oauth-authorization-server
```

**Response (with Auth.md agent_auth block):**

```json
{
  "resource": "https://arfat.is-a.dev",
  "authorization_servers": ["https://arfat.is-a.dev"],
  "scopes_supported": ["openid", "profile", "email", "read", "write"],
  "bearer_methods_supported": ["header"],
  "issuer": "https://arfat.is-a.dev",
  "authorization_endpoint": "https://arfat.is-a.dev/api/auth/authorize",
  "token_endpoint": "https://arfat.is-a.dev/api/auth/token",
  "registration_endpoint": "https://arfat.is-a.dev/api/auth/register",
  "revocation_endpoint": "https://arfat.is-a.dev/api/auth/revoke",
  "introspection_endpoint": "https://arfat.is-a.dev/api/auth/introspect",
  "jwks_uri": "https://arfat.is-a.dev/.well-known/jwks.json",
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "urn:ietf:params:oauth:grant-type:token-exchange",
    "urn:workos:agent-auth:grant-type:claim"
  ],
  "agent_auth": {
    "skill": "https://arfat.is-a.dev/auth.md",
    "register_uri": "https://arfat.is-a.dev/api/auth/register",
    "identity_endpoint": "https://arfat.is-a.dev/api/auth/register",
    "claim_endpoint": "https://arfat.is-a.dev/api/auth/claim",
    "claim_uri": "https://arfat.is-a.dev/api/auth/claim",
    "revocation_uri": "https://arfat.is-a.dev/api/auth/revoke",
    "events_endpoint": "https://arfat.is-a.dev/api/auth/events",
    "identity_types_supported": ["identity_assertion", "anonymous", "service_auth"],
    "identity_assertion": {
      "assertion_types_supported": ["urn:ietf:params:oauth:token-type:id-jag", "verified_email"],
      "credential_types_supported": ["bearer_token", "api_key", "http_message_signature"],
      "claim_uri": "https://arfat.is-a.dev/api/auth/claim",
      "revocation_uri": "https://arfat.is-a.dev/api/auth/revoke"
    },
    "anonymous": {
      "credential_types_supported": ["bearer_token", "ephemeral_key"],
      "claim_uri": "https://arfat.is-a.dev/api/auth/claim"
    },
    "service_auth": {
      "credential_types_supported": ["bearer_token", "api_key"],
      "claim_uri": "https://arfat.is-a.dev/api/auth/claim"
    },
    "events_supported": [
      "revocation",
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
```

## Step 2 — Pick an Identity Flow

1. **Identity Assertion Flow (`identity_assertion`)**:
   - For agent providers with user identity assertions (ID-JAG `urn:ietf:params:oauth:token-type:id-jag` or verified email `verified_email`).
2. **Anonymous Flow (`anonymous`)**:
   - Self-registration without upfront identity. Receives a pre-claim credential immediately. Claim ceremony can be completed at any time.
3. **Service Auth Flow (`service_auth`)**:
   - Provide email as login hint at registration, followed by verification ceremony.

## Step 3 — Register Agent

Send a POST request to `https://arfat.is-a.dev/api/auth/register`:

```http
POST /api/auth/register
Content-Type: application/json

{
  "type": "anonymous"
}
```

**Response:**

```json
{
  "type": "anonymous",
  "agent_id": "agent_anon_...",
  "identity_assertion": "assert_agent_anon_...",
  "token_endpoint": "https://arfat.is-a.dev/api/auth/token",
  "claim_uri": "https://arfat.is-a.dev/api/auth/claim",
  "expires_in": 3600,
  "status": "pre_claim"
}
```

## Step 4 — User Claim Ceremony (When Applicable)

Complete user verification at `https://arfat.is-a.dev/api/auth/claim`:

```http
POST /api/auth/claim
Content-Type: application/json

{
  "user_code": "123456"
}
```

## Step 5 — Obtain Access Token

Request an OAuth 2.0 Bearer token at `https://arfat.is-a.dev/api/auth/token`:

```http
POST /api/auth/token
Content-Type: application/json

{
  "grant_type": "client_credentials"
}
```

**Response:**

```json
{
  "access_token": "agtt_...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "openid profile email read write"
}
```

## Step 6 — Make Authenticated API Calls

Include the access token in HTTP headers:

```http
GET /api/mcp
Authorization: Bearer <access_token>
```

## Step 7 — Token Revocation & Security Events

Revoke active credentials:

```http
POST /api/auth/revoke
Content-Type: application/json

{
  "token": "<access_token>"
}
```

Push security events (RFC 8417 / RFC 8935) to `https://arfat.is-a.dev/api/auth/events`.

## Contact & Support

- **Maintainer**: Momin Mohammed Arfat
- **Email**: [arfat19118@gmail.com](mailto:arfat19118@gmail.com)
- **GitHub**: [https://github.com/mdarfatwork](https://github.com/mdarfatwork)
- **Auth.md Standard**: [https://workos.com/auth-md](https://workos.com/auth-md)
- **Agent Skill Reference**: [https://isitagentready.com/.well-known/agent-skills/auth-md/SKILL.md](https://isitagentready.com/.well-known/agent-skills/auth-md/SKILL.md)