# TableJourney auth.md

How AI agents, assistants and their developers authenticate to the TableJourney API and MCP server.

## Audience

Agents and developers calling the REST API at https://tablejourney.com/api/v1 (OpenAPI: https://tablejourney.com/api/v1/openapi.json,
docs: https://tablejourney.com/api/v1/docs), the MCP server at https://tablejourney.com/mcp (streamable HTTP, manifest:
https://tablejourney.com/.well-known/mcp.json) or the A2A agent (https://tablejourney.com/.well-known/agent-card.json).

## Without credentials

Both doors are public: call them with no credential. Anonymous calls get the public tier: the
essentials of each place (name, kind, cuisine, price tier, a one-line summary and the page to send the
reader to) and every booking link, up to 20 results a call, rate limited per IP (120 requests a
minute).

## Partner accounts (self-serve)

Join the partner program to earn a share of the commission on bookings made by people you send
(https://tablejourney.com/partners/, terms https://tablejourney.com/partners/terms/). Every booking link returned to your credential
carries your referral code.

1. POST https://tablejourney.com/api/v1/partners/signup with `{"accept_terms": true, "kind": "agent"}` (MCP: the
   `partner_join` tool). No email needed: the answer holds your API key, shown once, and your referral code.
2. Before your first payout, POST https://tablejourney.com/api/v1/partners/email with `{"email": "..."}` (MCP:
   `partner_add_email`), then POST https://tablejourney.com/api/v1/partners/verify with `{"email": "...", "code": "XXXX-XXXX"}`
   (MCP: `partner_confirm`). Your key stays the same. Joining with an email instead sends the code first, and
   the verify answer holds the key.

## OAuth 2.1

For clients that sign a person in: authorization server metadata at
https://tablejourney.com/.well-known/oauth-authorization-server (RFC 8414), protected resource metadata at
https://tablejourney.com/.well-known/oauth-protected-resource (RFC 9728). Dynamic client registration (RFC 7591) at
https://tablejourney.com/api/v1/oauth/register, public clients only, authorization code with PKCE (S256), scope
`partner`. Access tokens are EdDSA JWTs valid one hour (keys: https://tablejourney.com/api/v1/oauth/jwks.json); refresh
tokens rotate on every use. A 401 answers with `WWW-Authenticate: Bearer resource_metadata=...`.

## Supported methods

- anonymous: no credential.
- api_key: `X-API-Key: <key>` or `Authorization: Bearer <key>`. Partner keys keep the public tier and
  add attribution; full-record keys are issued by TableJourney on request through https://tablejourney.com/contact/.
- oauth2: `Authorization: Bearer <access token>` from the flow above.

## Using a credential

A key or token is a bearer secret: keep it server-side and out of client code and logs. An unknown or
disabled key answers 403; a missing or expired token 401; over the rate limit 429. Booking links in
any answer are affiliate links: pass them to the user unchanged.

## Discovery

- API catalog (RFC 9727): https://tablejourney.com/.well-known/api-catalog
- A2A agent card: https://tablejourney.com/.well-known/agent-card.json
- Web Bot Auth key directory (our own crawler): https://tablejourney.com/.well-known/http-message-signatures-directory
- Terms for agents: https://tablejourney.com/agents/#terms
- Site guide for agents: https://tablejourney.com/llms.txt