# Kasada auth.md

This document describes how agents register for the Kasada marketing site APIs. The resource server is `https://www.kasada.io`; the authorization server is `https://www.kasada.io`.

## 1. Discover

Fetch Protected Resource Metadata (RFC 9728):

```http
GET /.well-known/oauth-protected-resource HTTP/1.1
Host: www.kasada.io
```

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

Fetch Authorization Server metadata (RFC 8414):

```http
GET /.well-known/oauth-authorization-server HTTP/1.1
Host: www.kasada.io
```

Read the `agent_auth` block: `skill`, `register_uri`, `claim_uri`, `revocation_uri`, `identity_types_supported`, per-type `*_supported` arrays, and `events_supported`.

On `401 Unauthorized` from protected APIs, agents may also read `WWW-Authenticate: Bearer resource_metadata="https://www.kasada.io/.well-known/oauth-protected-resource"`.

Machine-readable URLs:

- PRM: `https://www.kasada.io/.well-known/oauth-protected-resource`
- Authorization server: `https://www.kasada.io/.well-known/oauth-authorization-server`
- Register: `https://www.kasada.io/.well-known/agent/auth`
- Claim: `https://www.kasada.io/.well-known/agent/auth/claim`
- Revoke: `https://www.kasada.io/.well-known/agent/auth/revoke`

## 2. Pick a method

- **ID-JAG** (`identity_assertion` + `urn:ietf:params:oauth:token-type:id-jag`) when the agent provider mints an ID-JAG for this audience.
- **Verified email** (`identity_assertion` + `verified_email`) when only a verified email is available; complete the claim ceremony.
- **Anonymous** when neither is available; optional claim upgrades scopes later.

Cross-check your choice against `agent_auth.identity_types_supported` and the matching `*_supported` arrays before calling `register_uri`.

## 3. Scopes

- `resources:search` — access to scoped public APIs

See `/.well-known/api-catalog` for public HTTP APIs.

## 4. Register

```http
POST /.well-known/agent/auth HTTP/1.1
Host: www.kasada.io
Content-Type: application/json
```

**Identity assertion (ID-JAG):**

```json
{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<id-jag-jwt>",
  "requested_credential_type": "access_token"
}
```

**Anonymous:**

```json
{
  "type": "anonymous",
  "requested_credential_type": "api_key"
}
```

## 5. Claim ceremony

1. `POST /.well-known/agent/auth/claim` with `claim_token` and user email (anonymous start).
2. User reads OTP from email.
3. `POST /.well-known/agent/auth/claim/complete` with `claim_token` and `otp`.

## 6. Use the credential

Present credentials as `Authorization: Bearer <credential>` on protected API requests.

## 7. Revocation

Agents do not call revoke directly for provider-driven flows. Providers may POST to `https://www.kasada.io/.well-known/agent/auth/revoke`; agents detect revocation on the next `401` and restart discovery.

Treat Protected Resource Metadata and Authorization Server JSON as authoritative if this file conflicts with them.