# AgentsMarkdown auth.md

AgentsMarkdown supports three agent authentication patterns.

## Anonymous capability links

Agents can create an anonymous document with `POST https://agentsmarkdown.com/new`. The response includes an owner capability URL containing `?key=...`. Share keys can grant `view`, `comment`, `suggest`, `edit`, or `owner` roles and may be sent as `?key=` or `X-Share-Key`.

## Human account sessions

Humans authenticate through mere.world. Agents and CLIs can use the device flow exposed by AgentsMarkdown:

- Start device login: `POST https://agentsmarkdown.com/api/cli/device/start`
- Poll device token: `POST https://agentsmarkdown.com/api/cli/device/token`
- Use the returned app-session token as `Authorization: Bearer asess_...`

The authorization server is https://mere.world. Protected resource metadata is available at https://agentsmarkdown.com/.well-known/oauth-protected-resource.

```json agent_auth
{
  "skill": "https://agentsmarkdown.com/auth.md",
  "register_uri": "https://mere.world/auth/oauth2/register",
  "identity_types_supported": ["verified_email", "anonymous"],
  "credential_types_supported": ["oauth2_authorization_code", "oauth2_device_code", "capability_url"],
  "verified_email": {
    "assertion_types_supported": ["verified_email"],
    "credential_types_supported": ["oauth2_authorization_code", "oauth2_device_code"],
    "claim_uri": "https://agentsmarkdown.com/sign-in"
  },
  "anonymous": {
    "credential_types_supported": ["capability_url"],
    "claim_uri": "https://agentsmarkdown.com/new"
  }
}
```

## Agent bearer tokens

AgentsIdentify bearer tokens with the `ai_` prefix can be sent as `Authorization: Bearer ai_...` when configured. Share links remain the least-ceremony path for scoped document collaboration.

## Discovery

- OAuth authorization server metadata: https://agentsmarkdown.com/.well-known/oauth-authorization-server
- OpenID configuration: https://agentsmarkdown.com/.well-known/openid-configuration
- Protected resource metadata: https://agentsmarkdown.com/.well-known/oauth-protected-resource
- Agent guide: https://agentsmarkdown.com/agents.md
- API catalog: https://agentsmarkdown.com/.well-known/api-catalog