# Authenticating with BlockWill as an Agent

BlockWill is a digital inheritance and estate-planning platform. This document
tells AI agents how to authenticate. Today, **all publicly documented endpoints
are read-only and require no authentication.** A scoped, authenticated
programmatic API for account and partner integrations arrives with the public
launch in Q1 2026; you can register interest now.

## Discover

Start from the protected-resource metadata:

- Protected resource metadata (RFC 9728): `https://www.blockwill.io/.well-known/oauth-protected-resource`
- Authorization server metadata (RFC 8414): `https://www.blockwill.io/.well-known/oauth-authorization-server`

The authorization-server metadata includes an `agent_auth` block describing the
`register_uri`, `claim_uri`, and `revocation_uri`, plus the supported
`identity_types_supported` and the credential request shape per type.

If you call the authenticated API without a token, you receive a `401` with a
discovery hint:

```
WWW-Authenticate: Bearer resource_metadata="https://www.blockwill.io/.well-known/oauth-protected-resource"
```

Probe it: `GET https://www.blockwill.io/api/v1`.

## Pick a method

`identity_types_supported` advertises:

- `anonymous` — for the public read-only endpoints (`/api/content`, `/api/faq`,
  `/api/schema`, `/ask`, `/mcp`). No registration, no token. Use these today.
- `identity_assertion` — for the authenticated API (post-launch). Supported
  assertion types include verified email and `urn:ietf:params:oauth:token-type:id-jag`
  (identity assertion JWT authorization grant / id-jag).

For anything you can do today, choose `anonymous` and call the endpoint directly.

## Register

To request programmatic (authenticated) access ahead of launch, register at the
`register_uri`:

```
POST https://www.blockwill.io/api/agent-auth/register
Content-Type: application/json

{ "client_name": "Your agent", "contact_email": "you@example.com", "intended_use": "..." }
```

Pre-launch this records your interest and returns guidance; live credential
issuance turns on at launch. Partners can also email partners@blockwill.io.

## Claim the credential

After registration, claim credentials at the `claim_uri`:

```
POST https://www.blockwill.io/api/agent-auth/claim
```

Pre-launch this returns the current status of your request. At launch it returns
a short-lived bearer token scoped to the permissions you were granted.

## Use the credential

Send the bearer token on requests to the authenticated API:

```
GET https://www.blockwill.io/api/v1/...
Authorization: Bearer <token>
```

Scopes follow least privilege (for example `content:read`, `faq:read`). Request
only the scopes you need.

## Errors

Errors are returned as structured JSON:

```json
{ "error": { "code": "unauthorized", "message": "...", "hint": "See https://www.blockwill.io/auth.md" } }
```

- `401 unauthorized` — missing/invalid token; read the `WWW-Authenticate` header.
- `403 insufficient_scope` — token lacks a required scope.
- `429 rate_limited` — back off using the `Retry-After` header.

## Revocation

Revoke a credential at the `revocation_uri`:

```
POST https://www.blockwill.io/api/agent-auth/revoke
```

## Summary for agents

- Public, read-only data: call `/api/content`, `/api/faq`, `/api/schema`,
  `/ask`, or the MCP server at `/mcp` — no auth.
- Authenticated API: discover via the well-known metadata, register, then claim
  a bearer token at launch.
- OpenAPI: https://www.blockwill.io/openapi.json