# auth.md — Realie authentication for agents

Sign in with OAuth against Realie's MCP resource. Do not create an OAuth app in the Clerk dashboard. MCP hosts discover the authorization server and register themselves (DCR).

## Resource and discovery

- MCP resource: https://app.realie.ai/api/mcp
- Protected resource metadata: https://app.realie.ai/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://app.realie.ai/.well-known/oauth-authorization-server
- Issuer: https://clerk.realie.ai

`initialize` and `tools/list` work without a token. `tools/call` returns HTTP 401 with `WWW-Authenticate` pointing at the protected-resource metadata.

Do not use https://docs.realie.ai/mcp for property data. That server searches documentation only.

## Sign in (new or existing account)

1. Add `https://app.realie.ai/api/mcp` in the MCP host, or run `realie login`.
2. Complete Clerk sign-up or sign-in in the browser (`accounts.realie.ai`).
3. If this is a new Realie account, open https://app.realie.ai/developer and add a payment method. OAuth does not mint an API key. Property calls need a billed user.

## After OAuth

- MCP: the host sends the Clerk access token. Request `offline_access` when the host sends scopes.
- CLI: `realie login` exchanges that token for the existing API key and stores it in `~/.realie/config.json`.
- REST and CI: `Authorization: Bearer YOUR_API_KEY` or `REALIE_API_KEY`.

```bash
realie login
```

```http
Authorization: Bearer YOUR_API_KEY
```

## Endpoints

- MCP: https://app.realie.ai/api/mcp
- REST API base: `https://app.realie.ai/api`
- Docs: https://docs.realie.ai/api-reference/property-data
- OpenAPI: https://docs.realie.ai/api-reference/openapi.json
- Agent hub (Markdown): https://www.realie.ai/agents.md
- Billing: https://app.realie.ai/billing

## Notes

- Keys are account-scoped and share the plan's monthly token allowance with Platform usage.
- Rotate keys from the dashboard if leaked.
- Terms: https://www.realie.ai/terms