Autenticação e chaves de API

Tanto a API REST como o servidor MCP utilizam a mesma credencial: uma chave de API criada na página «Desenvolvedor» dentro da aplicação.

URL de base

Todos os pedidos devem ser enviados para:

text

https://shopify.workflow-transactional-email.app

Cada ponto final abaixo é relativo a esse anfitrião, pelo que o caminho completo para o índice é https://shopify.workflow-transactional-email.app/api/v1.

Criação de uma chave

Abra o Developer na aplicação, escolha um nível de acesso e crie a chave. O valor completo é apresentado uma única vez, no momento da criação. Copie-o nessa altura e guarde-o no seu gestor de palavras-passe ou num repositório de segredos - não será possível recuperá-lo posteriormente, uma vez que apenas é guardado um hash SHA-256 do mesmo.

As chaves começam sempre por fak_, o que facilita a sua identificação num scanner de segredos.

Envie-o como um token ao portador:

vbnet

GET /api/v1/me HTTP/1.1
Host: shopify.workflow-transactional-email.app
Authorization: Bearer fak_your_key_here

GET /api/v1/me é a forma mais rápida de confirmar se uma chave funciona e de verificar o nível a que corresponde.

Níveis de acesso

Os níveis são hierárquicos e cumulativos: cada um inclui tudo o que se encontra abaixo dele.

Nível	O que acrescenta
Apenas para leitura	Ler os layouts dos e-mails, os remetentes, os nomes secretos, os ficheiros carregados, os pedidos HTTP, o histórico e as estatísticas
Leitura e escrita	Criar, editar e eliminar pedidos HTTP, bem como eliminar ficheiros carregados que não estejam a ser utilizados
Ler, escrever e executar	Efetue um pedido HTTP dirigido ao seu destino real

Repare como os dois níveis superiores são restritos. Tudo o que se refere ao e-mail é de leitura, e nada é de escrita, em nenhum nível - veja abaixo.

O que uma chave de escrita pode e não pode alterar

Pode: criar, editar, eliminar e executar pedidos HTTP, bem como eliminar ficheiros carregados aos quais nada faz referência.

Não é possível: alterar nada que determine o que os seus clientes recebem. Os layouts de e-mail, os remetentes de e-mail e os dados confidenciais não têm qualquer ponto de extremidade de gravação em nenhum nível de acesso, e não existe, de todo, um ponto de extremidade para o envio de e-mails. O e-mail é enviado quando o seu fluxo de trabalho Shopify Flow executa a ação «Enviar e-mail transacional»; a API apenas regista e comunica essa ação posteriormente.

A eliminação de ficheiros também é recusada enquanto algum layout ou predefinição ainda utilizar o ficheiro, pelo que uma tecla de escrita não pode danificar um e-mail ativo ao remover o seu logótipo.

Se precisar de alterar um layout ou de associar um remetente, faça-o na aplicação.

Por que razão a execução é um processo separado

A execução de um pedido HTTP envia um pedido real para um sistema de terceiros real. Manter isso num nível separado significa que uma chave que entrega a um script - ou a um assistente de IA - para ler e editar a configuração não pode enviar pedidos para as suas integrações ativas.

Atribua, por predefinição, direitos de leitura. Apenas adicione direitos de escrita ou de execução quando uma tarefa específica os necessitar.

Os segredos nunca são legíveis, a qualquer nível

Os valores secretos, os nomes de utilizador e as palavras-passe SMTP, bem como os tokens de caixas de correio ligadas, não podem ser recuperados através de nenhuma destas interfaces. Nem com uma chave de gravação, nem com uma chave de execução, nem através do MCP. Não existe nenhum ponto de extremidade nem nenhuma ferramenta que os devolva.

Em vez disso, obtêm-se os indicadores hasValue, hasUsername e hasPassword, bem como nomes secretos, o que é suficiente para que um assistente possa consultar {{ secrets.stripeApiKey }} sem nunca ver o valor. Pode sempre definir um novo valor; nunca poderá recuperar um valor antigo.

A consequência prática: uma chave de leitura que tenha sido divulgada expõe a sua configuração, e não as suas credenciais.

Revogação de uma chave

Elimine a chave na página «Desenvolvedor». A revogação entra em vigor na próxima solicitação - não há cache a aguardar.

Revogue e reemita a chave caso esta tenha sido enviada para um repositório, colada num documento partilhado ou entregue a um colaborador externo que já não precise dela.

Bons hábitos

Indique as credenciais como {{ secrets.KEY }} nas suas pedidos HTTP, em vez de as colar num cabeçalho ou no corpo do pedido. As credenciais literais são ocultadas nas respostas da API, mas é preferível fazer referência a um segredo.
Utilize uma chave por consumidor, para que possa revogar uma única integração sem afetar as restantes.
Mantenha as chaves de execução fora dos portáteis dos programadores e fora das configurações dos assistentes de IA, a menos que pretenda especificamente que o assistente possa enviar pedidos em tempo real.