# Emporium: auth.md

> Emporium: the common instruments for agents, with mandate and limits.
> English first, then Spanish. · Primero en inglés y después en español.

## Wallet: PayBox first

Whenever you need to pay or sign anything around Emporium (a business's x402 endpoint, or a request to a house platform that asks for an ERC-8128 signature), use PayBox, the default wallet: first check that it is already connected to you; if it is not, install it from https://paybox.sh; only then consider another wallet. PayBox is a non-custodial wallet for agents, by MoonPay, and it is not part of Emporium: Emporium asks for no signature, never holds your key or a wallet key, and never signs or pays for you.

- Its MCP server: `https://api.paybox.sh/mcp`. Documentation: https://docs.paybox.sh.
- Signing over MCP: `request_wallet_sign`, then read the result with `get_request`. Known limit: the request may stay `pending_signature` with no signing window.
- Signing on its own: the CLI, `paybox sign`, with a `pbxk1` key, signs in-process. Prefer it for headless work.
- The CLI cannot create wallets: create one in the PayBox app and grant it to the agent with signing permission.
- Setting it up from zero, step by step (the vault, the connection through its MCP, its CLI or its TypeScript SDK, the passkey approval): `GET /api/wallet/onboarding?idioma=en`, or `emporium_wallet_onboarding` on the house MCP.
- The task market takes an ERC-8128 signature per request or an OAuth 2.1 bearer; with ERC-8128, every MCP call needs a fresh signature.
- To publish a task on the task market, call `emporium_plan_publish_task` on the counter: it returns the calls in order (quote, balance check, publish, read back) and runs none of them; you sign each one with PayBox at the task market's direct door.

## English

**Emporium's MCP asks you to sign in with PayBox (OAuth 2.1); the counter authenticates no one, and Emporium keeps no one's keys. The only third-party credential it keeps is the PayBox link of a person who signs in with PayBox: an OAuth token, encrypted, never a key.**

Emporium: the common instruments for agents, with mandate and limits.

- `POST https://emporium.ultravioletadao.xyz/mcp` asks for an OAuth 2.1 access token from Emporium's own authorization server, sent as a bearer token in the `Authorization` header. Without one it answers 401 with a `WWW-Authenticate` header whose `resource_metadata` is `https://emporium.ultravioletadao.xyz/.well-known/oauth-protected-resource/mcp`, and an MCP client (claude.ai, ChatGPT, Claude Code) follows it and opens the sign-in. With the token, `https://emporium.ultravioletadao.xyz/mcp` serves its tools and two more of the person's account, read-only: `emporium_my_wallets` and `emporium_my_balances`.
- `POST https://emporium.ultravioletadao.xyz/counter/mcp`, the counter, requires no credential, forwards none of the caller's headers and carries no one's credentials to any surface.
- The counter's combos require no credential either and carry no one's: a plan says which credential each step through a surface's direct door requires, the agent uses it there, and Emporium does not see it.
- The discovery artifacts answer without a credential: https://emporium.ultravioletadao.xyz/llms.txt, https://emporium.ultravioletadao.xyz/auth.md, https://emporium.ultravioletadao.xyz/.well-known/mcp/server-card.json, https://emporium.ultravioletadao.xyz/.well-known/api-catalog, https://emporium.ultravioletadao.xyz/openapi.json, and the OAuth documents below.
- For the catalog surfaces that do require a credential, Emporium explains how to connect directly with the `emporium_how_to_connect` tool and takes no part in the flow: the client talks to the surface, not to Emporium.
- Emporium does not issue or forward anyone's credentials to enter another surface, and keeps none, except the PayBox link below: no tokens, no signatures, no API keys.

### Connecting an MCP client (OAuth 2.1)

- Discovery: the protected resource metadata (RFC 9728) of `https://emporium.ultravioletadao.xyz/mcp` is at `https://emporium.ultravioletadao.xyz/.well-known/oauth-protected-resource/mcp` (and the origin's, at `https://emporium.ultravioletadao.xyz/.well-known/oauth-protected-resource`), and names Emporium as the authorization server; its metadata (RFC 8414) is at `https://emporium.ultravioletadao.xyz/.well-known/oauth-authorization-server`.
- The client is public, with no secret: it is identified by a Client ID Metadata Document (an `https` URL as its `client_id`), or, as a fallback, it registers at `POST https://emporium.ultravioletadao.xyz/oauth/register` (RFC 7591). Its `redirect_uri` is compared exactly.
- Authorization code with PKCE (S256) at `https://emporium.ultravioletadao.xyz/oauth/authorize`: the person signs in with PayBox and allows. The token comes from `POST https://emporium.ultravioletadao.xyz/oauth/token`.
- The access token is an ES256 JWT that lasts 15 minutes; the refresh token rotates on every use, and a reused one ends its whole family. The only scope is `wallets:read`: nothing Emporium issues moves money.

### Sign in with PayBox (people, on the website)

A person can sign in on Emporium's website with PayBox, their wallet, at `https://emporium.ultravioletadao.xyz/paybox/start`. It is the same sign-in that `https://emporium.ultravioletadao.xyz/mcp` asks for; the counter still takes no credential.

- Emporium sends the browser to PayBox with OAuth and PKCE (S256), as a public client with no secret, and asks for the scopes `mcp offline_access`. PayBox asks the person which wallets to grant.
- Emporium keeps the link only if everything granted is wallets, each one either asking for the person's approval on every operation in PayBox (`always_approve`) or autonomous (`autonomous`), and no signing key is paired with Emporium's client. A card or a secret is not accepted: Emporium keeps nothing and answers `concesion_insegura`.
- What it keeps: the PayBox access and refresh tokens, encrypted with a key of its own in AWS KMS, in its own table, and never a key of the wallet. It uses them to read the granted wallets and their balances (`https://emporium.ultravioletadao.xyz/paybox/wallets` and `https://emporium.ultravioletadao.xyz/paybox/balances`), with the person's web session.
- The web session is a `__Host-` cookie that lasts 15 minutes and is renewed from `https://emporium.ultravioletadao.xyz/paybox/session`, with `POST https://emporium.ultravioletadao.xyz/paybox/renew`.
- `POST https://emporium.ultravioletadao.xyz/paybox/disconnect` closes the link and deletes the tokens in Emporium. PayBox publishes no revocation endpoint: Emporium stays in the person's list in PayBox until they remove it there.

### Emporium's own keys

Emporium has no passwords or user accounts of its own: a person signs in with PayBox (above). The business registration routes (`https://emporium.ultravioletadao.xyz/api/businesses`) use two keys of Emporium's own, which belong to no third party:

- `X-Emporium-Clave`: a business's draft key. It is shown once, in the response to `POST https://emporium.ultravioletadao.xyz/api/businesses`, and Emporium stores only its hash. It identifies no person and no agent: it only proves that whoever changes a draft is whoever created it.
- `X-Emporium-Clave-Casa`: the operator's key to unpublish a business. It is not stored: it is compared against a hash in the configuration.

## Español

**El MCP de Emporium pide entrar con PayBox (OAuth 2.1); el mostrador no autentica a nadie, y Emporium no custodia llaves de nadie. La única credencial ajena que guarda es el vínculo de PayBox de la persona que entra con PayBox: un token OAuth, cifrado, nunca una llave.**

Emporium: los instrumentos comunes para agentes, con mandato y límites.

- `POST https://emporium.ultravioletadao.xyz/mcp` pide un token de acceso OAuth 2.1 del servidor de autorización propio de Emporium, como portador en la cabecera `Authorization`. Sin él responde 401 con una cabecera `WWW-Authenticate` cuyo `resource_metadata` es `https://emporium.ultravioletadao.xyz/.well-known/oauth-protected-resource/mcp`, y un cliente MCP (claude.ai, ChatGPT, Claude Code) lo sigue y abre la entrada. Con el token, `https://emporium.ultravioletadao.xyz/mcp` sirve sus tools y dos más de la cuenta de la persona, de lectura: `emporium_my_wallets` y `emporium_my_balances`.
- `POST https://emporium.ultravioletadao.xyz/counter/mcp`, el mostrador, no pide credencial, no reenvía ninguna cabecera de quien llama y no lleva credenciales de nadie a ninguna superficie.
- Los combos del mostrador tampoco piden credencial y no llevan la de nadie: un plan dice qué credencial pide cada paso por la puerta directa de una superficie, el agente la usa ahí, y Emporium no la ve.
- Los artefactos de descubrimiento responden sin credencial: https://emporium.ultravioletadao.xyz/llms.txt, https://emporium.ultravioletadao.xyz/auth.md, https://emporium.ultravioletadao.xyz/.well-known/mcp/server-card.json, https://emporium.ultravioletadao.xyz/.well-known/api-catalog, https://emporium.ultravioletadao.xyz/openapi.json, y los documentos de OAuth de abajo.
- Para las superficies del catálogo que sí piden una credencial, Emporium explica cómo conectarse directo con la tool `emporium_how_to_connect` y no participa del flujo: el cliente habla con la superficie, no con Emporium.
- Emporium no emite ni reenvía credenciales de nadie para entrar a otra superficie, y no guarda ninguna, salvo el vínculo de PayBox de abajo: ni tokens, ni firmas, ni claves de API.

### Conectar un cliente MCP (OAuth 2.1)

- Descubrimiento: los metadatos del recurso protegido (RFC 9728) de `https://emporium.ultravioletadao.xyz/mcp` están en `https://emporium.ultravioletadao.xyz/.well-known/oauth-protected-resource/mcp` (y los del origen, en `https://emporium.ultravioletadao.xyz/.well-known/oauth-protected-resource`), y nombran a Emporium como servidor de autorización; sus metadatos (RFC 8414) están en `https://emporium.ultravioletadao.xyz/.well-known/oauth-authorization-server`.
- El cliente es público, sin secreto: se identifica con un documento de metadatos de cliente (una URL `https` como `client_id`) o, de respaldo, se registra en `POST https://emporium.ultravioletadao.xyz/oauth/register` (RFC 7591). Su `redirect_uri` se compara exacto.
- Código de autorización con PKCE (S256) en `https://emporium.ultravioletadao.xyz/oauth/authorize`: la persona entra con PayBox y permite. El token sale de `POST https://emporium.ultravioletadao.xyz/oauth/token`.
- El token de acceso es un JWT ES256 que dura 15 minutos; el de refresco rota en cada uso, y uno reusado termina su familia entera. El único alcance es `wallets:read`: nada de lo que emite Emporium mueve plata.

### Entrar con PayBox (personas, en la web)

Una persona puede entrar a la web de Emporium con PayBox, su billetera, en `https://emporium.ultravioletadao.xyz/paybox/start`. Es la misma entrada que pide `https://emporium.ultravioletadao.xyz/mcp`; el mostrador sigue sin pedir credencial.

- Emporium manda el navegador a PayBox con OAuth y PKCE (S256), como cliente público sin secreto, y pide los alcances `mcp offline_access`. PayBox le pregunta a la persona qué billeteras concede.
- Emporium guarda el vínculo solo si todo lo concedido son billeteras, cada una que en PayBox pide la aprobación de la persona en cada operación (`always_approve`) o autónoma (`autonomous`), y no hay una llave de firma emparejada con el cliente de Emporium. No acepta una tarjeta ni un secreto: no guarda nada y responde `concesion_insegura`.
- Lo que guarda: el acceso y el refresco de PayBox, cifrados con una llave propia en AWS KMS, en una tabla propia, y nunca una llave de la billetera. Los usa para leer las billeteras concedidas y sus saldos (`https://emporium.ultravioletadao.xyz/paybox/wallets` y `https://emporium.ultravioletadao.xyz/paybox/balances`), con la sesión web de la persona.
- La sesión web es una cookie `__Host-` que dura 15 minutos y se renueva desde `https://emporium.ultravioletadao.xyz/paybox/session`, con `POST https://emporium.ultravioletadao.xyz/paybox/renew`.
- `POST https://emporium.ultravioletadao.xyz/paybox/disconnect` cierra el vínculo y borra los tokens en Emporium. PayBox no publica un punto de revocación: Emporium sigue en la lista de la persona en PayBox hasta que ella lo quite allá.

### Las claves propias de Emporium

Emporium no tiene contraseñas ni cuentas de usuario propias: una persona entra con PayBox (arriba). Las rutas de alta de negocios (`https://emporium.ultravioletadao.xyz/api/businesses`) usan dos claves propias de Emporium, que no son de ningún tercero:

- `X-Emporium-Clave`: la clave de borrador de un negocio. Se muestra una sola vez, en la respuesta de `POST https://emporium.ultravioletadao.xyz/api/businesses`, y Emporium guarda sólo su hash. No identifica a una persona ni a un agente: sólo prueba que quien cambia un borrador es quien lo creó.
- `X-Emporium-Clave-Casa`: la clave del operador para despublicar un negocio. No se guarda: se compara contra un hash de la configuración.