Criar chave de API

POST/v1/instances/{id}/api-keysdesde M11token da instância ou admin

Quando usar

Cria uma chave (lzk_...) presa a esta instância, com escopos:

- read: rotas GET de leitura — instância, mensagens, fila, chats, contatos, mídia, grupos, comunidades, perfil, privacidade, bloqueados, eventos (SSE), uso, status, canais (e publicações), etiquetas e perfil comercial. Nunca QR, configurações, hook de agente, convites de grupo nem escritas de status, canal ou etiqueta. - send: POST /messages e GET /messages/{msg_id} (status do envio).

Qualquer outra rota responde 403 forbidden, inclusive /mcp, webhooks, ações de ciclo de vida e a gestão de chaves. A chave aparece uma única vez nesta resposta (só o hash fica guardado). Opcionais: ip_allowlist (IPs/CIDRs) e expires_in_seconds. Até 50 chaves por instância (as expiradas são descartadas). Apagar a instância apaga as chaves.

Uma chave também respeita a ip_allowlist da instância; no stream SSE ela nunca recebe instance.qr nem instance.pair_code, e um stream aberto é encerrado em até um heartbeat (15s) quando a chave é revogada, expira ou sai da allowlist. Rotacionar o token da instância revoga as chaves criadas com ele (as criadas pelo admin continuam).

Autenticação

Aceita o token da instância (só a própria instância) ou o token admin. Um token de outra instância recebe 403 forbidden (ou 404 not_found em webhooks de outra instância).

Parâmetros

Caminho

Nome	Tipo	Descrição
idobrigatório	string	Id da instância (inst_...).

Corpo (JSON)

Nome	Tipo	Descrição
nameobrigatório	string	(até 100)
scopesobrigatório	"read" | "send"[]
ip_allowlist	string[]
expires_in_seconds	integer	0 ou ausente: não expira.

Exemplo

cURL

curl -s -X POST "$LITEZAP_URL/v1/instances/$ID/api-keys" \
  -H "Authorization: Bearer $LITEZAP_TOKEN" \
  -d '{"name":"painel do cliente","scopes":["read"],"ip_allowlist":["203.0.113.0/24"],"expires_in_seconds":2592000}'

Node.js

const res = await fetch("http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/api-keys", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LITEZAP_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "painel do cliente",
    "scopes": [
      "read"
    ],
    "ip_allowlist": [
      "203.0.113.0/24"
    ],
    "expires_in_seconds": 2592000
  }),
});
console.log(res.status, res.status === 204 ? "" : await res.json());

Python

import os
import requests

r = requests.post(
    "http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/api-keys",
    headers={"Authorization": f"Bearer {os.environ['LITEZAP_TOKEN']}"},
    json={
        "name": "painel do cliente",
        "scopes": ["read"],
        "ip_allowlist": ["203.0.113.0/24"],
        "expires_in_seconds": 2592000,
    },
    timeout=150,
)
print(r.status_code, r.json() if r.content else "")

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/api-keys", strings.NewReader(`{"name":"painel do cliente","scopes":["read"],"ip_allowlist":["203.0.113.0/24"],"expires_in_seconds":2592000}`))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("LITEZAP_TOKEN"))
  req.Header.Set("Content-Type", "application/json")
  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  out, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.Status, string(out))
}

PHP

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client(['base_uri' => 'http://localhost:8787']);
$res = $client->request('POST', '/v1/instances/inst_7f3a9c2e5b1d4086/api-keys', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('LITEZAP_TOKEN')],
    'json' => [
        'name' => 'painel do cliente',
        'scopes' => ['read'],
        'ip_allowlist' => ['203.0.113.0/24'],
        'expires_in_seconds' => 2592000,
    ],
    'http_errors' => false,
]);
echo $res->getStatusCode(), ' ', $res->getBody(), PHP_EOL;

Nos exemplos, LITEZAP_URL é a URL base (ex.: http://localhost:8787) e o token vem deLITEZAP_TOKEN (instância) ou LITEZAP_ADMIN_TOKEN.

Resposta

201 Chave criada.

Campos de object

api_key	APIKey
api_key.id	string	Id da chave (key_...).
api_key.instance_id	string
api_key.name	string
api_key.scopes	"read" | "send"[]
api_key.ip_allowlist	string[]
api_key.created_at	string
api_key.expires_at	string	Ausente: não expira.
api_key.last_used_at	string	Atualizado no máximo uma vez por minuto.
key	string	A chave (lzk_...). Mostrada só uma vez.

{
  "api_key": {
    "id": "key_5c1e9a7d3b2f4086",
    "instance_id": "inst_7f3a9c2e5b1d4086",
    "name": "painel do cliente",
    "scopes": [
      "read"
    ],
    "ip_allowlist": [
      "203.0.113.0/24"
    ],
    "created_at": "2026-10-18T09:00:00Z",
    "expires_at": "2026-11-17T09:00:00Z"
  },
  "key": "lzk_RXhlbXBsby1uYW8tdXNlLWVzdGEtY2hhdmU"
}

Erros

Código	HTTP	Retentável	O que fazer
validation_failed	400	não	Corrija o corpo ou os parâmetros; a message diz o campo.
unauthorized	401	não	Envie Authorization: Bearer <token> válido.
forbidden	403	não	Use o token certo (admin, ou o da própria instância).
instance_not_found	404	não	Confira o id da instância.

Todo erro usa o envelope {"error":{"code","message","retryable"}}. Tabela completa em Erros.

Equivalente na Z-API: (sem equivalente). Veja Migrar da Z-API.

Outras operações de Plataforma: Operação em lote · Listar chaves de API · Revogar chave de API · Gerar link de pareamento · Revogar links de pareamento · Uso da instância