# Auth

Pricesaurus API authentication for agents and HTTP clients.

## Protected resource metadata

Machine file: `/.well-known/oauth-protected-resource` (RFC 9728).

The resource is `/api/v1`. Tokens are Sanctum personal access tokens with the `developer` ability. There is no public authorization server and no client registration in this version.

## Discover

The API lives at `/api/v1`. The machine-readable contract is `/openapi.json`. A signed-in person on Plus or Max creates a token at `/api-keys`.

## Pick a method

Use a personal access token. A logged-in human creates a token once; an agent or SDK reuses it as a Bearer token. MCP product tools at `/.well-known/mcp` (also `/mcp/watch`) use the same header.

## Register

No client registration. A Pricesaurus account on Plus or Max is enough.

## Claim

A signed-in user creates a token at `/api-keys` (web). The plaintext token is shown once.

```
POST /api-keys
```

Store the token; it cannot be retrieved later.

## Exchange

None. The token you received is already an access token.

## Use the access_token

Send it on every `/api/v1` request:

```
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json
```

Example:

```
curl -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -d '{"url":"https://www.amazon.com/dp/B00CH9QWOU"}' \
  /api/v1/extract
```

Unauthenticated calls to `/api/v1/products` return HTTP 401 JSON and `WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"`.

## Errors

Invalid or revoked tokens also return 401. Extraction failures return 422 or 503 with:

```
{"error":{"code":"no_price","message":"...","retryable":true,"driver":"scrapingbee"}}
```

## Revocation

Delete the token at `/api-keys`. After revoke, the Bearer token stops working immediately.