# auth.md

This document tells **agents** how to register and authenticate with Omnicost.

Humans should use the browser form at https://omnicost.com/register.

## Audience

Autonomous agents that need catalog search, item detail, MCP tools, or a
workspace. Scrapers that only hit HTML `/register` receive **HTTP 402**.

## Methods

### 1. x402 agent registration (preferred)

`POST https://omnicost.com/api/v1/agents/register`

```json
{ "email": "agent@example.com", "name": "My Agent" }
```

Unauthenticated calls return **402 Payment Required** with x402
`accepts[]` (USDC on Base). Retry the same POST with an `X-PAYMENT`
header. Success (201) returns a one-shot `omc_pub_` API key.

See https://omnicost.com/.well-known/agent-skills/register-agent/SKILL.md

### 2. OAuth client_credentials

- Authorization server: https://omnicost.com/.well-known/oauth-authorization-server
- Protected resource: https://omnicost.com/.well-known/oauth-protected-resource
- Token: `POST https://omnicost.com/api/oauth/token`
- Dynamic registration: `POST https://omnicost.com/api/oauth/register`

### 3. Human-provisioned key

A person opens https://omnicost.com/register, then creates an org API key. Send
`Authorization: Bearer omc_org_…` or `omc_pub_…`.

### 4. Card checkout for Omnicost Pro

`POST https://omnicost.com/api/v1/checkout/agent`

```json
{ "email": "agent@example.com", "plan": "monthly" }
```

`plan` is `weekly`, `monthly` or `yearly`. Without `key_id` you get a
new free `omc_pub_` key (`key.secret`, shown once) plus a Stripe
`checkout_url` for a person to pay by card. To upgrade a key you already
have, add `"key_id"` and send that key as `Authorization: Bearer`. After
payment the key gets Omnicost Pro limits. Check the result at
`https://omnicost.com/api/v1/checkout/agent/done?session_id=cs_…`. At most 5 checkout calls
per hour from one network address.

## Credential use

Send the key as `Authorization: Bearer <key>` on:

- https://omnicost.com/api/v1/*
- https://omnicost.com/api/mcp

Without a key, https://omnicost.com/api/v1/items, https://omnicost.com/api/v1/search and https://omnicost.com/api/mcp
return 401. Bots that call /api/v1 without a key get 402 with x402 payment
instructions (see https://omnicost.com/.well-known/x402).

## Rate limits

- Organization API key: 600 req/min per organization, on REST and /api/mcp.
- Organization key with Omnicost Pro: 1000 req/min, on REST and /api/mcp.
- https://omnicost.com/api/v1/search: 60 req/min for every caller.

## Scopes

`catalog:read`, `catalog:search`