Autenticação

A API pública Maestron usa autenticação por API Key — não por login de usuário. Uma chave pertence a uma única empresa e representa essa empresa em toda requisição: não há conceito de usuário autenticado do lado da API pública, e a chave nunca tem o bypass de dono de empresa que existe no aplicativo Maestron.

Gerando uma chave

A chave é gerada dentro do painel Maestron, em Configurações → API Keys, por um usuário com a permissão settings.api_keys.manage na empresa. Ao criar a chave você escolhe:

Nome — identifica a chave na lista (ex.: “Integração ERP”).
Escopos — quais operações a chave pode executar. Ver Escopos & Permissões. Você só pode conceder escopos que a sua própria conta possui na empresa.
Ambiente — live ou test (ver Sandbox abaixo).
Expiração — opcional.
Allowlist de IP — opcional, lista de IPs/CIDRs que podem usar a chave.

O segredo completo é exibido uma única vez, no momento da criação (e novamente se a chave for rotacionada). Guarde-o com o mesmo cuidado de uma senha — a Maestron nunca reenvia o segredo em texto claro depois disso.

Formato do segredo

maestron_pk_9f1a3c7e2b8d4f6a0c5b9d3e7f1a4c8b6e2d0f9a
maestron_pk_test_9f1a3c7e2b8d4f6a0c5b9d3e7f1a4c8b6e2d0f9a

O prefixo indica o ambiente: maestron_pk_ para chaves live, maestron_pk_test_ para chaves test. Uma chave test só aceita requisições cujo segredo tenha o prefixo _test_; o ambiente é fixado na criação e não muda depois.

Header `Authorization`

Toda requisição autenticada envia o segredo no header HTTP Authorization:

Authorization: Bearer maestron_pk_9f1a3c7e2b8d4f6a0c5b9d3e7f1a4c8b6e2d0f9a

Não existe refresh, expiração automática por tempo de sessão nem renovação de token — a chave vale até ser revogada, rotacionada ou atingir a data de expiração configurada (se houver).

Resolução automática de empresa

A empresa é a dona da chave e é resolvida a partir dela — não há e não deve ser enviado nenhum identificador de empresa em nenhuma requisição. Cada chave pertence a exatamente uma empresa; para integrar mais de uma empresa, gere uma chave em cada uma.

Ambientes `live` e `test`

Toda chave nasce com um ambiente fixo:

Ambiente	Prefixo do segredo	Efeito nas escritas
`live`	`maestron_pk_`	Grava de verdade.
`test`	`maestron_pk_test_`	Roda a mesma validação e a mesma lógica de negócio, mas nada é persistido — a operação inteira roda dentro de uma transação que é sempre desfeita.

Use uma chave test para validar sua integração sem risco de gravar dados incorretos na empresa. O detalhamento do comportamento de sandbox está em Sandbox & Idempotência.

Falha de autenticação

Segredo ausente, mal formado, revogado, expirado ou com IP fora da allowlist da chave — em qualquer um desses casos a resposta é 401:

{
  "message": "Não autenticado.",
  "data": null
}

Revogação e rotação

A chave pode ser revogada ou rotacionada a qualquer momento pelo painel Maestron (mesma tela de criação). A rotação gera um novo segredo e corta o segredo anterior imediatamente — não há período de carência em que os dois segredos funcionam ao mesmo tempo. Planeje a troca do segredo na sua integração antes de rotacionar em produção.

Captação de leads: token publicável

A captação de leads usa outra credencial: um token publicável (mcf_...) que vai na URL, não no header. Ele não é uma API Key — sua única capacidade é criar um negócio no funil e estágio do formulário que o gerou, sem leitura nem escrita de qualquer outro recurso. É seguro colar no HTML público de um site. Não confunda os dois formatos: maestron_pk_... autentica a API de parceiros; mcf_... só serve para captação.

Para os códigos de status e o formato das respostas de erro, consulte Erros. Para os limites de requisição, consulte Rate limiting.