# auth.md — amberbird.ai agent registration

This document describes how AI agents authenticate with amberbird.ai public APIs.

## Audience

Automated agents that need programmatic access to waitlist, guide, and discovery endpoints.

## Resource server

- **Resource identifier:** `https://amberbird.ai/api`
- **Protected resource metadata:** `/.well-known/oauth-protected-resource`
- **Authorization server metadata:** `/.well-known/oauth-authorization-server`

## Registration

Agents may self-register without prior credentials:

```http
POST /api/agent/register
Content-Type: application/json

{"client_name": "my-agent"}
```

The response includes `client_id`, `client_secret`, supported `grant_types`, and `scopes`.

## Supported identity flows

| Flow | Identity type | Credential | Notes |
|------|---------------|------------|-------|
| Anonymous agent | `anonymous` | Bearer token via client credentials | Default for discovery and guide reads |
| Verified email | `verified_email` | Bearer token + identity assertion | For actions tied to a verified user email |

## Scopes

- `guides:read` — List and read published immigration guides
- `waitlist:write` — Join the product waitlist
- `contact:write` — Submit contact form messages

## Discovery

- API catalog: `/.well-known/api-catalog`
- OpenAPI spec: `/openapi.json`
- Agent skills: `/.well-known/agent-skills/index.json`
- MCP server card: `/.well-known/mcp/server-card.json`

## Human support

Questions about agent access: [contact](/contact)