Pular para o conteúdo

Criar chave

POST/tenants/{id}/api-keys

Cria uma chave de API para o projeto. A chave é enviada em toda requisição como Authorization: Bearer <chave> ou X-Api-Key: <chave>. A resposta traz a chave inteira em key uma única vez: a apiwpp guarda só o hash SHA-256 dela, então não há como mostrá-la de novo. Guarde-a num cofre de segredos agora. Escopo necessário: keys:write.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador do projeto (tenantId) que recebe a chave.

Corpo da requisição

namestringobrigatório

Para que a chave serve (por exemplo, CRM produção). De 1 a 100 caracteres; um nome só com espaços é recusado.

de 1 a 100 caracteres
scopesstring[]obrigatório

O que a chave pode fazer: pelo menos um escopo, sem repetição, entre connections:read, connections:write, messages:send, templates:write, webhooks:write, logs:read, usage:read, keys:read e keys:write. Uma chave de API só concede os escopos que ela mesma tem.

mínimo de 1 itemsem itens repetidos
expiresAtstring · date-time | null

Quando a chave para de funcionar (data e hora ISO 8601, no futuro). null ou ausente: nunca expira. Uma chave que expira só cria chaves que expiram até a mesma data.

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
201A chave criada, com a chave inteira em key, mostrada só desta vez. Cada chave traz id, tenantId (o projeto), organizationId (a organização do projeto), name, prefix (identifica a chave; não é secreto), maskedKey (wag_live_<prefixo>_…, para reconhecer a chave), scopes, status (active, expired ou revoked), createdBy (apiKey:<id> da chave que a criou, user:<id> do usuário do painel ou platform), createdAt, lastUsedAt (atualizado no máximo uma vez por minuto), expiresAt, revokedAt e rotatedAt (quando uma rotação a substituiu).
400FST_ERR_VALIDATIONO corpo não segue o schema: sem name ou scopes, name com mais de 100 caracteres, scopes vazio, repetido ou com um escopo desconhecido, expiresAt fora do formato de data e hora, ou id que não é um UUID. message diz o que está errado.
400name só tem espaços (name must not be blank), ou expiresAt não está no futuro (expiresAt must be in the future).
401Sem chave de API, ou com uma chave inválida: desconhecida, revogada, expirada ou de um projeto desativado. O corpo é {"error": "Unauthorized"}.
403A credencial não tem o escopo keys:write (This credential lacks the keys:write scope); no painel, só donos e administradores criam chaves.
403A chave que chama pediu escopos que ela não tem (An API key cannot grant scopes it does not hold: …, com a lista), ou uma validade maior que a dela: a mensagem diz até quando a nova chave pode valer (expiresAt must be … or earlier).
404O projeto não existe ou não é de quem chama (Tenant not found): uma chave de API alcança só o próprio projeto, e o de outra pessoa responde igual a um que não existe.
409O projeto já tem 50 chaves ativas: revogue uma antes de criar outra. Ou o projeto está desativado; como a chave de um projeto desativado já responde 401, esse caso só aparece para quem chama pelo painel.
429Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After

Detalhes

Uma chave nunca cria outra mais poderosa: uma chave de API só concede escopos que ela mesma tem, e uma chave que expira só cria chaves que expiram até a mesma data (e não chaves sem expiração). Pedir mais do que isso responde 403.

Um projeto tem no máximo 50 chaves ativas (nem revogadas nem expiradas); a próxima responde 409 até você revogar uma. Um projeto desativado não recebe chaves novas (409).

A chave vale só para este projeto e fica com createdBy igual a apiKey:<id> da chave que a criou (ou user:<id> quando criada no painel). Veja Autenticação e Escopos.

Guia: Autenticação

Esta página ajudou? · Atualizado em 28 set 2026