# auth.md — Marketdata.ai

You are an agent integrating with Marketdata.ai. This document describes how to authenticate and register for API access.

## Discovery

1. Fetch `https://marketdata.ai/.well-known/oauth-protected-resource` for Protected Resource Metadata (PRM).
2. Fetch `https://marketdata.ai/.well-known/oauth-authorization-server` for Authorization Server metadata and the `agent_auth` block.

## Registration and credentials

Marketdata.ai supports two authentication methods for machine access:

**1. OAuth 2.1 authorization code + PKCE (MCP connector clients).**
The authorization server lives at `https://marketdata.ai/oauth/authorize` and `https://marketdata.ai/oauth/token` (S256 PKCE required, advertised via `code_challenge_methods_supported`). During consent the user selects which account the connection may access; issued tokens are bound to that account. Use this for claude.ai custom connectors and other OAuth-capable MCP clients — add `https://marketdata.ai/mcp` as a remote MCP server and the client discovers everything else via the `.well-known` documents.

**2. Bearer API tokens (human-in-the-loop provisioning).**

1. Sign in at `https://marketdata.ai/users/sign_in` (or create an account at `https://marketdata.ai/users/sign_up`).
2. Open **Settings → API Tokens** at `https://marketdata.ai/api_tokens` and create a dedicated token for the agent integration.
3. Send `Authorization: Bearer <token>` on MCP (`POST https://marketdata.ai/mcp`) and REST API requests.

Revoke OAuth connections from your AI client, and API tokens at `https://marketdata.ai/api_tokens`, when an integration is retired.

## Supported scopes

| Scope | Use |
|-------|-----|
| `mcp` | MCP JSON-RPC tools at `/mcp` (OAuth tokens and API tokens) |
| `api` | REST API (`/api/v1/me`, account-scoped JSON routes; API tokens only) |

## Agent auth methods (metadata)

The `agent_auth` block in `/.well-known/oauth-authorization-server` advertises:

- `register_uri` — `https://marketdata.ai/users/sign_up` (account registration)
- `claim_uri` — `https://marketdata.ai/users/sign_in` (sign-in to provision tokens)
- `revocation_uri` — `https://marketdata.ai/api_tokens` (revoke issued tokens)
- `identity_types_supported` — `anonymous`, `service_auth` (Bearer token provisioning via UI)
- `identity_assertion.assertion_types_supported` — `verified_email` (email-verified account linking)

## API usage

- MCP guide: `https://marketdata.ai/llms.txt`
- Interactive OpenAPI docs: sign in on a paid plan, then open `https://marketdata.ai/api-docs`
- API catalog: `https://marketdata.ai/.well-known/api-catalog`

## Policies

- Terms: `https://marketdata.ai/terms`
- Privacy: `https://marketdata.ai/privacy`
- Security contact: `https://marketdata.ai/.well-known/security.txt`