# auth.md

Service: **Email Audit Engine** (`https://emailauditengine.com`)

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.

## agent_auth

```json
{
  "agent_auth": {
    "skill": "https://emailauditengine.com/auth.md",
    "register_uri": "https://emailauditengine.com/api/auth/register",
    "identity_endpoint": "https://emailauditengine.com/api/auth/register",
    "claim_endpoint": "https://emailauditengine.com/api/auth/claim",
    "claim_uri": "https://emailauditengine.com/api/auth/claim",
    "events_endpoint": "https://emailauditengine.com/api/auth/events",
    "revocation_uri": "https://emailauditengine.com/api/auth/signout",
    "revocation_endpoint": "https://emailauditengine.com/api/auth/signout",
    "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": ["access_token", "api_key"],
      "claim_uri": "https://emailauditengine.com/api/auth/claim"
    },
    "anonymous": {
      "credential_types_supported": ["api_key"],
      "claim_uri": "https://emailauditengine.com/api/auth/claim"
    },
    "service_auth": {
      "credential_types_supported": ["password", "oauth"],
      "claim_uri": "https://emailauditengine.com/api/auth/claim"
    },
    "events_supported": [
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
```

## Step 1 — Discover

Discovery is two hops:

### 1a. Fetch the Protected Resource Metadata

```
GET https://emailauditengine.com/.well-known/oauth-protected-resource
```

Returns `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`.

### 1b. Fetch the Authorization Server Metadata

```
GET https://emailauditengine.com/.well-known/oauth-authorization-server
```

Contains the `agent_auth` block with `identity_endpoint`, `claim_endpoint`, and `identity_types_supported`.

## Step 2 — Pick a method

| Identity type | When to use |
| --- | --- |
| `identity_assertion` | You have a user session and can mint an ID-JAG audience-bound to this service. |
| `service_auth` | You have only the user's email. Claim ceremony required. |
| `anonymous` | You have neither. Claim ceremony optional / deferred. |

## Step 3 — Register

### identity_assertion + id-jag

```
POST https://emailauditengine.com/api/auth/register
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion": "<signed-id-jag-jwt>"
}
```

### service_auth (email + password)

```
POST https://emailauditengine.com/api/auth/register
Content-Type: application/json

{
  "identity_type": "service_auth",
  "name": "My Agent",
  "email": "agent@example.com",
  "password": "..."
}
```

### anonymous

```
POST https://emailauditengine.com/api/auth/register
Content-Type: application/json

{
  "identity_type": "anonymous"
}
```

## Step 4 — Claim (if needed)

For `anonymous` or `service_auth` registrations that need user verification:

```
POST https://emailauditengine.com/api/auth/claim
Content-Type: application/json

{
  "agent_id": "<agent-id-from-step-3>"
}
```

## Step 5 — Obtain a session

Exchange credentials for a session cookie:

```
POST https://emailauditengine.com/api/auth/callback/credentials
Content-Type: application/x-www-form-urlencoded

email=...&password=...&csrfToken=...
```

Subsequent calls should include the returned `next-auth.session-token` cookie or a `Bearer` token.

## Scopes

- `openid`           — identity
- `profile`          — display name, picture
- `email`            — email address
- `offline_access`   — long-lived refresh token

## Revocation

```
POST https://emailauditengine.com/api/auth/signout
```

## Discovery Links

- OAuth Authorization Server: `https://emailauditengine.com/.well-known/oauth-authorization-server`
- OpenID Connect: `https://emailauditengine.com/.well-known/openid-configuration`
- Protected Resource: `https://emailauditengine.com/.well-known/oauth-protected-resource`
- API Catalog: `https://emailauditengine.com/.well-known/api-catalog`
- MCP Server Card: `https://emailauditengine.com/.well-known/mcp/server-card.json`
- Agent Skills Index: `https://emailauditengine.com/.well-known/agent-skills/index.json`

## Contact

- Site: https://emailauditengine.com
- Support: developers@thinkgrid.io