Gerando sua API Key

A API Key é gerada dentro do painel Maestron (não pela API pública em si) por um usuário com a permissão settings.api_keys.manage na empresa. Este guia cobre o formulário de criação e o ciclo de vida da chave depois de gerada.

Passo a passo

No painel Maestron, acesse Configurações → API Keys.
Clique em Nova chave e preencha o formulário (campos detalhados abaixo).
Confirme a criação. O segredo completo é exibido uma única vez — copie e guarde antes de fechar a tela.
Use o segredo no header Authorization: Bearer <segredo> das suas chamadas à API pública. Ver Autenticação.

Campos do formulário

Campo	Obrigatório	Descrição
Nome	sim	Identifica a chave na listagem (ex.: “Integração ERP”). Até 120 caracteres.
Escopos	sim, ao menos 1	Quais operações a chave pode executar. Você só pode conceder escopos que sua própria conta possui na empresa. Ver Escopos & Permissões.
Ambiente	não, padrão `live`	`live` grava de verdade; `test` roda tudo em uma transação sempre desfeita. Ver Sandbox & Idempotência. Fixado na criação — não muda depois.
Expiração	não	Data e hora futura a partir da qual a chave para de funcionar (passa a responder `401`). Sem valor, a chave não expira por tempo.
Allowlist de IP	não, até 50 entradas	IPs ou blocos CIDR (IPv4 ou IPv6) autorizados a usar a chave. Uma requisição de IP fora da lista é tratada como não autenticada (`401`). Lista vazia libera qualquer origem.

Escolhendo escopos

Conceda apenas os escopos que a integração realmente usa. Para o fluxo de Primeiros passos, por exemplo, bastam:

crm.view — leitura.
crm.funnels.manage — criar/editar pipelines.
crm.leads.create e crm.leads.edit — criar e movimentar negócios.
crm.leads.close — marcar como ganho/perdido/reaberto.

O catálogo completo e o que cada escopo libera estão em Escopos & Permissões.

Editando uma chave

Depois de criada, você pode alterar pelo mesmo painel:

Nome — só rótulo, não afeta as chamadas.
Escopos — passa a valer o novo conjunto na chamada seguinte. Reduzir escopos é a forma de tirar uma permissão da integração sem trocar o segredo. Continua valendo o limite: você só concede escopos que a sua conta possui.
Expiração — definir, adiar ou remover. Nova data tem que ser futura.
Allowlist de IP — ajustar ou limpar a lista.

O ambiente (live / test) é fixado na criação e não pode ser editado. Para trocar de ambiente, gere outra chave.

Ambiente `live` vs `test`

Gere uma segunda chave com ambiente test para desenvolvimento e QA da sua integração — o segredo tem o prefixo maestron_pk_test_ e nenhuma escrita feita com ela é persistida. Use a chave live (prefixo maestron_pk_) só quando a integração já estiver validada.

Rotação

Rotacionar gera um novo segredo para a mesma chave (mesmo nome, mesmos escopos, mesmo ambiente) e corta o segredo anterior imediatamente — não há período de carência em que os dois funcionam ao mesmo tempo. Planeje a troca do segredo na sua integração antes de rotacionar uma chave em produção, para não gerar uma janela de 401.

Revogação

Revogar invalida a chave permanentemente; qualquer chamada com o segredo revogado passa a responder 401. Uma chave só pode ser excluída da listagem depois de revogada.

Acompanhando o uso

Cada chave tem uma visão de uso no painel, com:

Último uso — data/hora e IP da última requisição feita com a chave.
Limite do minuto corrente — quanto resta das 120 requisições/minuto da chave (ver Rate limiting).
Últimas chamadas — método, rota, código de status e IP das requisições recentes. O corpo da requisição e da resposta nunca é registrado.

Erros

Para o formato de erro e os códigos de status, veja Erros.