> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Enroll with a claim code

> Connect without hosting /.well-known — paste a one-time claim from the user’s Mac or phone.

Some assistants cannot publish keys on a public HTTPS domain (sandboxed VMs, consumer
chat apps, agents that are not a vendor product yet). Those agents **enroll** with a
one-time claim code the user creates in Federated Agent Use.

Publisher domains that already host `/.well-known/fau-agent` should keep using
[Identity](https://docs.fau.run/developer/connect/identity.md). Enrollment is the Lane B path; it never pretends to be a
verified corporate domain.

## What the user does

1. On the **Mac menu bar** → **Connect agent…**, or on the **phone** → **Settings** →
   **Connect an agent**.
2. They pick Muse / Instinct / Custom (or another catalog entry) and create a claim.
3. They copy the paste message and drop it into your chat / settings.
4. You enroll, then sign MCP requests with the returned `keyid`.

Phone prompts show their chosen label (for example “Muse”) with an **unverified /
you connected this** badge until a real publisher JWKS or attestation exists.

## Enroll endpoint

```
POST https://<node-hostname>/agent/enroll
Content-Type: application/json
```

Unsigned. The claim code *is* the capability (single use, \~30 minutes).

```json theme={null}
{
  "claim_code": "AB12CD34",
  "kid": "k1",
  "pubkey": "<base64url of raw 32-byte Ed25519 public key>",
  "agent_name": "optional override of the display label"
}
```

### Success `200`

```json theme={null}
{
  "agent_id": "enrolled:a1b2c3d4e5f60718",
  "keyid": "enrolled:a1b2c3d4e5f60718#k1",
  "kid": "k1",
  "display_name": "Muse",
  "publisher_verified": false,
  "expected_publisher": "muse.ai",
  "node_url": "https://n….relay.fau.run/",
  "mcp_url": "https://n….relay.fau.run/mcp"
}
```

Use `keyid` exactly in RFC 9421 `Signature-Input` (tag `fau-agent`). Do **not** invent
`instinct.ai` or another corporate domain as `keyid`.

### Errors `400`

| Detail contains | Meaning |
| - | - |
| not recognised | Wrong code |
| already used | Claim was spent |
| expired | Ask the user for a fresh claim |
| pubkey must be… | Not 32-byte Ed25519 / not base64url |

## After enrollment

1. `GET https://<hostname>/.well-known/fau-node` (unsigned check).
2. Open an MCP session on `mcp_url` — see [Transport](https://docs.fau.run/developer/connect/transport.md) and
   [Signing](https://docs.fau.run/developer/connect/signing.md).
3. Call tools as usual. First access still needs a phone Allow.

Key resolution for `enrolled:…` identities is **local to the node** (no HTTPS fetch).
If the user removes the enrollment, signatures fail until they mint a new claim.

## Example

```bash theme={null}
# pubkey = base64url(raw 32-byte Ed25519 public key)
curl -sS -X POST 'https://n….relay.fau.run/agent/enroll' \
  -H 'content-type: application/json' \
  -d '{"claim_code":"AB12CD34","kid":"k1","pubkey":"…"}'
```

Then sign every `/mcp` request with `keyid` from the response. See
[Signing](https://docs.fau.run/developer/connect/signing.md) for the header set.

## Bridging to publisher verification later

When your product hosts `/.well-known/fau-agent` (or issues short-lived instance
attestations), new sessions can use the DNS `keyid`. Existing enrollments keep working
as unverified until the user reconnects with the publisher path. Catalog
`expected_publisher` is a hint only — it never grants a verified badge by itself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.