API Admin › Guias

Autenticação: integrações, tokens e escopos

A integração

Cada sistema que trabalha na loja é uma integração, criada no painel em Configurações › Integrações. Só o dono e o gerente da loja criam e cuidam das integrações. A integração não é uma pessoa: continua funcionando quando quem a criou sai da equipe, e o que ela muda fica registrado em nome dela.

Na criação, marque só os escopos de que a integração precisa e escolha a validade do primeiro token.

O token

Authorization: Bearer dnxa_...

• Começa com dnxa_ e tem 54 caracteres, só letras e números. O prefixo permite que ferramentas de varredura de segredos reconheçam o token esquecido num repositório.
• Aparece uma vez só, na criação. A plataforma guarda apenas o hash: não há como mostrar o token de novo. Perdeu, gere outro.
• É segredo de servidor. Guarde como uma senha, no servidor da integração, e nunca no código de uma página: a API não responde a navegadores de outra origem (não há CORS).
• Validade: sem validade, 90 dias ou 1 ano.
• Dois tokens ativos por integração, para trocar sem parar: gere o novo, troque no sistema da integração e revogue o antigo.
• Revogar vale na hora. A API confere o token a cada chamada.
• Quem cuida das integrações recebe um e-mail a cada token criado. Se ninguém da equipe o criou, revogue.
• O painel mostra o começo e o fim de cada token, o último uso e o IP de onde veio.

O token de uma integração não abre o painel, e o login de uma pessoa no painel não abre a API Admin: a pessoa entra pelo login do CLI (abaixo), que vale só nos temas.

O login do CLI pela conta

O CLI de temas entra também pela conta de quem está no computador, sem pedir um token ao dono da loja: denaryx login mostra um código, a pessoa o digita no painel (em denaryx.com/painel/cli), confere de onde veio o pedido e escolhe a loja. O CLI recebe um token de sessão:

Authorization: Bearer dnxp_...

• Começa com dnxp_ (de pessoal), no mesmo formato do token de integração. É do CLI: fica no arquivo de credenciais da pessoa e nunca vai para um servidor.
• Vale só nos temas: as rotas de /themes, GET /token e GET /shop. Nas outras, a resposta é 403 cli_session_not_allowed: para um ERP ou uma automação, use uma integração.
• Os escopos saem do papel da pessoa na loja, a cada chamada: read_themes e write_themes para quem tem o código dos temas (dono, gerente e Catálogo e vitrine) e publish_themes para quem publica tema com código próprio. Mudou o papel, muda o acesso; saiu da equipe, o acesso deixa de valer.
• Vale 90 dias. Cada pessoa tem até 10 acessos ativos por loja. Em Configurações › Integrações › Acessos pelo CLI, o dono e o gerente veem e revogam os de toda a equipe, e cada pessoa os seus; denaryx logout revoga o próprio. A pessoa recebe um e-mail a cada acesso autorizado.
• O que a sessão grava fica no nome da pessoa, como no painel.

O código do login vale 10 minutos e uma vez. Nunca digite no painel um código que outra pessoa mandou: quem tem o acesso trabalha nos temas em seu nome. Em CI, use o token de uma integração (DENARYX_TOKEN).

Escopos

Nenhum token alcança a conta de pagamento, a equipe, o domínio, os pedidos de privacidade, a medição, o frete nem as próprias integrações. E nenhum token tem mais acesso do que o papel de quem o criou.

Só os textos: write_content

É o escopo de um agente de SEO ou de conteúdo, sem o risco de mexer em preço e estoque. Ele muda:

• no produto (PATCH /products/{id}): title, description, seo e handle, e o texto de cada foto (PATCH /products/{id}/images/{image_id});
• na coleção (PATCH /collections/{id}): title, description, seo e handle;
• na marca (PATCH /brands/{id}): name, description, seo e handle;
• nas páginas institucionais: tudo, inclusive criar. A página criada pela integração nasce fora do ar e entra na vitrine com published: true num PATCH. Excluir fica no painel.

Um handle novo leva o endereço antigo ao novo (301): os buscadores não perdem a página.

Não muda preço, estoque, variantes, situação (active), fotos, especificações, coleções do produto, a árvore das coleções nem o modelo da página (template_suffix), e não cria nem exclui produto, coleção ou marca. O mesmo PATCH aceita os dois escopos: com write_content, um corpo com qualquer campo além dos textos é recusado inteiro, nada muda, e a resposta diz quais campos pedem write_products:

{
  "error": {
    "type": "permission_error",
    "code": "missing_scope",
    "message": "Com o escopo write_content, só os textos mudam. O campo em fields pede o escopo write_products.",
    "fields": [
      {
        "field": "active",
        "message": "Este campo pede o escopo write_products."
      }
    ]
  }
}

O servidor MCP segue a mesma regra, porque chama o mesmo serviço.

read_orders, write_orders e read_customers levam para fora da plataforma o nome, o e-mail, o telefone, o CPF e o endereço de quem comprou: a integração passa a responder por esses dados na LGPD. O read_reports não leva nenhum deles: só as vendas somadas.

Recusas

A loja suspensa fica sem a API Admin em toda rota, com qualquer token, até ser reativada; o motivo está no painel da loja. Os webhooks dela esperam a reativação (ver Webhooks).

Um endereço que manda tokens inválidos demais passa a receber 429 (too_many_invalid_tokens) por alguns minutos, mesmo com um token bom. Ver Limites.