Autenticación

Se emiten tres familias de credenciales a los clientes. Existe una cuarta, interna. Se lista aquí para que no tengas que ir a buscarla.

1. OAuth 2.1 con PKCE: el camino MCP

La forma principal en que un cliente de IA alcanza una tienda. Es un flujo de autorización completo, no una clave pegada:

1. El cliente descubre los metadatos del servidor de autorización.
2. El usuario llega a la pantalla de consentimiento en /oauth/authorize y ve exactamente qué scopes se solicitan.
3. El cliente intercambia el código, ligado a PKCE.
4. El token de acceso está acotado a un único storeId y se almacena hasheado en reposo.

Úsalo siempre que el cliente pueda negociar. Es el único camino donde el usuario ve y aprueba la lista de scopes, y el único donde después puedes acotar una concesión.

En modo OAuth, la cuenta del bearer se verifica en cada llamada, no solo el token. Un token vivo de una cuenta baneada o eliminada deja de funcionar.

2. bst_mcp_ — el bearer MCP estático

Para una máquina que no puede ejecutar el flujo OAuth: un job de CI, una ejecución sin navegador. Claude Code y Cursor leen un archivo de configuración y aun así inician sesión por OAuth; la clave es su alternativa, no su opción por defecto.

• Generado por tienda, desde los ajustes de la Custom App de Shopify.
• Almacenado como hash SHA-256; el texto plano se muestra una sola vez y nunca es re-derivable.
• Poseer la clave es la autorización. Está acotada a la tienda, así que no hay negociación de scope aparte.

La consecuencia de ese último punto es lo que hay que entender: una clave estática satisface la familia de herramientas relay, las que alcanzan Shopify a través del puente. No satisface las herramientas que protegen un recurso de BoostEcom cuyo permiso depende de una pertenencia a organización, porque en modo estático no hay un usuario identificado que verificar, y un permiso no verificable debe rechazar en lugar de dejar pasar. Ver Herramientas y scopes MCP.

3. bei_ — la clave de Intelligence

Un token de solo lectura para la Intelligence API.

• Lleva el scope read:intelligence, que ahora se aplica, no solo se almacena.
• El techo de tasa se cuenta por clave, no por dirección IP.
• Almacenado como hash SHA-256.

Cualquier cosa que no sea un simple Bearer bei_<hex> se rechaza de plano en lugar de degradarse a anónimo.

Ver Intelligence API.

4. bst_ — interno

Tokens generados por administradores con permisos roadmap.*, consumidos por un servidor MCP de roadmap interno. No se emite a clientes. Solo está listado para que ver un prefijo bst_ en un changelog no te haga buscar una clave que no puedes obtener.

Retirada: la familia sk_

Si encuentras una referencia a claves sk_ o a un endpoint de canal REST en un documento antiguo, ha desaparecido. Esas claves vivían en un mapa local al proceso, así que ninguna solicitud llevaba nunca una más allá de una instancia y cada ruta protegida respondía 401. La familia y el endpoint /api/channels/api se eliminaron en lugar de repararse.

Elegir

| Estás construyendo | Usa | |---|---| | Un cliente MCP capaz de hacer OAuth | OAuth 2.1 PKCE | | Un cliente MCP en una máquina sin navegador (CI, headless) | bst_mcp_ | | Un script de inteligencia de solo lectura | bei_ |