Autenticação

Três famílias de credencial são emitidas para clientes. Uma quarta existe e é interna. Está listada aqui para que você não saia procurando por ela.

1. OAuth 2.1 com PKCE: o caminho MCP

A forma primária de um cliente de IA alcançar uma loja. É um fluxo de autorização completo, não uma chave colada:

1. O cliente descobre os metadados do servidor de autorização.
2. O usuário chega na tela de consentimento em /oauth/authorize e vê exatamente quais escopos estão sendo solicitados.
3. O cliente troca o código, vinculado por PKCE.
4. O token de acesso é escopado a um único storeId e armazenado com hash em repouso.

Use isto sempre que o cliente puder negociar. É o único caminho onde o usuário vê e aprova a lista de escopos, e o único onde você pode depois estreitar uma concessão.

No modo OAuth, a conta do bearer é verificada a cada chamada, não apenas o token. O token ativo de uma conta banida ou excluída para de funcionar.

2. bst_mcp_: o bearer MCP estático

Para uma máquina que não consegue rodar o fluxo OAuth: um job de CI, uma execução sem navegador. O Claude Code e o Cursor leem um arquivo de configuração e mesmo assim se autenticam por OAuth; a chave é o recurso deles, não o padrão.

• Gerado por loja, nas configurações do Custom App da Shopify.
• Armazenado como hash SHA-256; o texto puro é mostrado uma vez e nunca pode ser re-derivado.
• Possuir a chave é a autorização. É escopada à loja, então não há negociação de escopo separada.

A consequência desse último ponto é o que importa entender: uma chave estática satisfaz a família de ferramentas relay: as ferramentas que alcançam a Shopify através da ponte. Ela não satisfaz ferramentas que protegem um recurso do BoostEcom cuja permissão depende de uma associação a uma organização, porque no modo estático não há usuário identificado para verificar, e uma permissão que não pode ser verificada deve recusar, nunca deixar passar. Veja Ferramentas e escopos MCP.

3. bei_: a chave de Intelligence

Um token somente leitura para a Intelligence API.

• Carrega o escopo read:intelligence, e esse escopo agora é aplicado, não apenas armazenado.
• O teto de taxa é contado por chave, não por endereço IP.
• Armazenado como hash SHA-256.

Qualquer coisa diferente de um simples Bearer bei_<hex> é recusada totalmente, em vez de rebaixada para anônimo.

Veja Intelligence API.

4. bst_: interna

Tokens gerados por admin carregando permissões roadmap.*, consumidos por um servidor MCP de roadmap interno. Não emitidos para clientes. Listado apenas para que ver um prefixo bst_ em um changelog não te mande caçar uma chave que você não pode obter.

Descontinuada: a família sk_

Se você encontrar uma referência a chaves sk_ ou a um canal REST em um documento antigo, ela se foi. Essas chaves viviam em um mapa local ao processo, então nenhuma requisição jamais carregou uma através de um limite de instância e toda rota protegida respondia 401. A família e o endpoint /api/channels/api foram removidos em vez de corrigidos.

Escolhendo

| Você está construindo | Use | |---|---| | Um cliente MCP que pode fazer OAuth | OAuth 2.1 PKCE | | Um cliente MCP em uma máquina sem navegador (CI, headless) | bst_mcp_ | | Um script de intelligence somente leitura | bei_ |