Criar chave
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.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador do projeto (tenantId) que recebe a chave.
Corpo da requisição
namestringobrigatórioPara que a chave serve (por exemplo, CRM produção). De 1 a 100 caracteres; um nome só com espaços é recusado.
scopesstring[]obrigatórioO 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.
expiresAtstring · date-time | nullQuando 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
| Código | Erro e descrição |
|---|---|
| 201 | A 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). |
| 400 | FST_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. |
| 400 | name só tem espaços (name must not be blank), ou expiresAt não está no futuro (expiresAt must be in the future). |
| 401 | Sem chave de API, ou com uma chave inválida: desconhecida, revogada, expirada ou de um projeto desativado. O corpo é {"error": "Unauthorized"}. |
| 403 | A credencial não tem o escopo keys:write (This credential lacks the keys:write scope); no painel, só donos e administradores criam chaves. |
| 403 | A 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). |
| 404 | O 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. |
| 409 | O 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. |
| 429 | Requisiçõ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