Chaves e níveis de acesso

Cada requisição leva a chave no cabeçalho X-API-Key. Você as cria no ByDomu, em Configurações › API e webhooks; a completa aparece uma só vez.

Publicáveis e secretas

Publicáveldomu_pk_live_

Para seu site e o navegador: pode ir no código da página.

portal:read · leads:write · booking:write · finder:write · events:write

Só o público e receber clientes.

Secretadomu_sk_live_

Só de um servidor: Zapier, Make, n8n, seu backend ou um cliente MCP.

Qualquer permissão: *:read e, com aprovação, *:write

Em um navegador responde 403.

As chaves antigas (domu_live_) continuam funcionando igual enquanto as revisamos.

Modo de teste

As chaves de teste (domu_sk_test_ e domu_pk_test_) têm todas as permissões sem solicitar acesso e só veem sua organização de teste, com dados de exemplo: nada do que você fizer com elas chega aos seus clientes. Limite: 100 requisições e 30 escritas por minuto.

Guia do modo de teste

Níveis de acesso

O que uma chave pode fazer depende do plano e do que o suporte aprovar. Nunca há API durante o teste grátis nem com o e-mail sem verificar.

NívelPlanosComo se obtém

1Chaves publicáveis300 requisições e 60 escritas por minuto · até 5 chavesQualquer plano pagoSem solicitação

2Secretas somente leitura60 requisições por minuto · até 2 chavesBusiness · EnterpriseAutomático

3Escritas, mensagens, webhooks e limites altosSob medida do aprovadoQualquer plano pagoRevisão do suporte

Mais limite ou mais permissões são pedidos em Configurações › API e webhooks.

Limites e paginação

Cada resposta diz quanto resta do minuto. As listas são paginadas com page e pageSize e trazem meta.total e meta.totalPages.

Cabeçalhos de resposta

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 41
Retry-After: 41            # só com 429
Idempotency-Status: replayed  # nova tentativa com a mesma Idempotency-Key

Erros

Sempre com o mesmo formato: { "error": { "code", "message" } }.

400VALIDATION_ERRORDados de entrada inválidos

401UNAUTHORIZEDChave ausente ou inválida

402PAYMENT_REQUIREDConta somente leitura: escrita recusada

403FORBIDDENA chave não tem essa permissão

403SECRET_KEY_IN_BROWSERChave secreta usada em um navegador

403API_ACCESS_REQUIREDO nível da conta não permite esta chave

403PLAN_LIMIT_REACHEDUm limite do plano foi atingido

404NOT_FOUNDRecurso não encontrado

409IDEMPOTENCY_CONFLICTIdempotency-Key reutilizada com outro corpo

409IDEMPOTENCY_IN_PROGRESSOutra requisição com a mesma Idempotency-Key ainda está em andamento

429RATE_LIMITEDLimite por minuto excedido

429TENANT_RATE_LIMITEDLimite de escritas por minuto da organização excedido