# BAGS auth.md

> Agent registration and authentication guide for the BAGS Agent API
> (https://www.getbags.app/api/v1). BAGS Agent lets merchants sell API calls to AI
> agents via x402 payment links.

## Who this is for

AI agents (and the developers operating them) that need authenticated
access to the BAGS Agent API: payment links, products, and transactions.

Anonymous, read-only surfaces do NOT require registration:

- MCP server: `https://www.getbags.app/api/mcp/mcp` (streamable HTTP, no auth)
- Public payment-link preview via the MCP tool
  `bags-preview-payment-link`
- x402 agentic payments: pay per-request with USDC instead of
  registering — see `https://www.getbags.app/api/v1` (returns an x402 challenge)
  and https://docs.getbags.app/docs/providers/sell-to-agents

## Registration (verified email, human-in-the-loop)

Supported registration methods: **verified email** (human-mediated).
Supported credential types: **API key** (`api_key`).

BAGS uses human-mediated registration. There is no unauthenticated
programmatic signup endpoint — do not POST to guessed registration URLs.

1. **Register**: direct your operator (a human) to the registration
   endpoint https://www.getbags.app/login to create a merchant account with a
   verified email address.
2. **Claim credentials**: the operator creates an API key from the
   "API keys" card in account settings at https://www.getbags.app/dashboard/settings.
   Live keys on agentic accounts are scoped to agentic endpoints
   (payment-link management and the account's own transactions).
3. **Hand the key to the agent** through your own secret-management
   channel. BAGS never re-displays a key after creation.

## Using credentials

Send the API key as a bearer token in the `Authorization` header:

```http
GET /api/v1/payment-links HTTP/1.1
Host: www.getbags.app
Authorization: Bearer bag_live_sk_...
```

- API base: `https://www.getbags.app/api/v1` (OpenAPI: `https://www.getbags.app/api/openapi.json`)
- 401 responses carry `WWW-Authenticate` with a `resource_metadata`
  pointer to /.well-known/oauth-protected-resource (RFC 9728).
- Agent-facing x402 links do not require buyer accounts or buyer API keys.

## Discovery documents

Plain URLs (no code formatting) so scanners that extract links from this
file resolve them verbatim:

- OAuth protected resource (RFC 9728): https://www.getbags.app/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414): https://www.getbags.app/.well-known/oauth-authorization-server
  — includes the agent_auth block describing this registration flow
- OIDC discovery: https://www.getbags.app/.well-known/openid-configuration
- API catalog (RFC 9727): https://www.getbags.app/.well-known/api-catalog

## Revocation

Operators rotate integration credentials from account settings. Treat
401 `invalid_token` responses as revocation and re-enter the claim
flow above.

## Support

- Docs: https://docs.getbags.app
- Master Services Agreement: https://www.getbags.app/merchant-agreement