# Conta e chaves

Fonte: https://lunahia.com.br/docs/conta-e-chaves

Tudo que o console faz com a sua conta também se faz pela API, porque o console é cliente dela. Este guia mostra o caminho completo: cadastrar, entrar, criar uma chave, usar os escopos, revogar, e ler a conta, o plano e o estado da plataforma.

## Como a API autentica

Toda rota de integração pede uma chave no cabeçalho `Authorization`, no formato `Bearer hlsn_...`. A chave carrega escopos: cada rota exige o seu, e uma chave sem o escopo recebe `403`. Sem chave, ou com uma chave inválida ou revogada, a resposta é `401`.

Há dois tipos de credencial. A **chave de integração** é a do seu servidor: vale até ser revogada. A **sessão** é a do console: vale oito horas, nasce do login, e não cria nem revoga chaves sozinha. Para criar uma chave, a sessão confirma a senha antes (passo 3 abaixo).

## 1. Cadastrar a conta

`POST /v1/operators/signup` cria a conta e o primeiro operador numa chamada só, sem credencial. A senha tem no mínimo 12 caracteres, e quem monta a tela lê esse mínimo em `GET /v1/public/password-policy` (`{ "minLength": 12 }`, sem credencial), em vez de copiar o número. A resposta é `201` e não traz sessão: o próximo passo é entrar.

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/signup" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br",
  "password": "uma frase longa que so voce sabe",
  "tenantName": "Sua Empresa"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/operators/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "ana@suaempresa.com.br",
    "password": "uma frase longa que so voce sabe",
    "tenantName": "Sua Empresa"
  }),
});
console.log(res.status, await res.json());
```

```python
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/operators/signup",
    json={
        "email": "ana@suaempresa.com.br",
        "password": "uma frase longa que so voce sabe",
        "tenantName": "Sua Empresa",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

```json
{
  "nextStep": "login"
}
```

A Luna manda um e-mail com um link de confirmação. Ele vale por sete dias e é aceito uma vez. A conta já lê a documentação e cria chaves antes de confirmar, mas só a conta confirmada abre sessão de conexão de número. Se o e-mail não chegou, `POST /v1/operators/confirmation/resend` envia de novo (só com a sessão do console, e há um teto de poucos reenvios por hora).

## 2. Entrar

`POST /v1/operators/login` troca e-mail e senha por uma credencial de sessão de oito horas. O campo `token` é o `Bearer` das próximas chamadas deste guia que usam a sessão. A recusa é sempre a mesma, seja senha errada ou conta inexistente.

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br",
  "password": "uma frase longa que so voce sabe"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/operators/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "ana@suaempresa.com.br",
    "password": "uma frase longa que so voce sabe"
  }),
});
console.log(res.status, await res.json());
```

```python
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/operators/login",
    json={
        "email": "ana@suaempresa.com.br",
        "password": "uma frase longa que so voce sabe",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

```json
{
  "tenantId": "0b5e3c1a-7d42-4f6a-9c18-2e7a1d5b8f90",
  "operatorId": "6a2d9f40-1b73-4e85-a0c6-3d8e5f7b9a12",
  "token": "hlsn_...",
  "expiresAt": "2026-10-28T20:00:00.000Z",
  "scopes": [
    "onboarding:write", "numbers:read", "numbers:write", "messages:read", "messages:write",
    "templates:read", "templates:write", "webhooks:read", "webhooks:write", "keys:read",
    "session:end", "session:elevate"
  ]
}
```

Guarde o token da sessão

```bash
export LUNA_SESSION="hlsn_..."
```

Para trocar a senha sabendo a de hoje, sem passar pelo "Esqueci minha senha", use `POST /v1/operators/password/change` com a sessão e o corpo `{ "currentPassword": "...", "newPassword": "..." }`. A resposta é `204`. A senha nova segue a mesma regra do cadastro, as outras sessões do operador são encerradas e a que pediu a troca continua valendo. Senha atual errada responde `401`, e há um teto de tentativas por sessão.

## 3. Confirmar a senha

Criar e revogar chave é uma ação sensível. `POST /v1/operators/step-up` confirma a senha do operador da sessão e abre uma janela de duas horas em que essa mesma sessão pode criar e revogar chaves. A resposta traz `elevatedUntil`, o fim da janela, e em `scopes` o que a janela empresta à sessão (`keys:write`). Passadas as duas horas, a senha é pedida de novo.

Com a sessão do passo 2

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/step-up" \
  -H "Authorization: Bearer $LUNA_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "uma frase longa que so voce sabe"
}'
```

```json
{
  "elevatedUntil": "2026-10-28T14:00:00.000Z",
  "scopes": ["keys:write"]
}
```

Para saber se a janela ainda está aberta sem pedir a senha à toa, leia `GET /v1/operators/session` com a sessão: `expiresAt` é o fim da sessão, `elevatedUntil` é o fim da janela (nulo sem janela ou com ela fechada) e `scopes` são os escopos que a sessão tem agora. Pede o escopo `session:end`, que a sessão do console já tem.

## 4. Criar uma chave

`POST /v1/api-keys` cria a chave. Peça só os escopos de que ela precisa: uma chave que só envia mensagem não deveria poder conectar número nem criar outras chaves. Com `externalId`, a chave é de UM cliente seu e só enxerga o que é dele. Com `mode: "test"`, a chave é de teste: ela envia sem ir à Meta, e só usa duas rotas (veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste)). A resposta traz o campo `secret` **uma única vez**: não há rota que o devolva depois, e quem o perde revoga a chave e cria outra.

Com a sessão, dentro da janela do passo 3

```bash
curl -X POST "https://api.lunahia.com.br/v1/api-keys" \
  -H "Authorization: Bearer $LUNA_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Integração de produção",
  "scopes": [
    "messages:write",
    "messages:read",
    "numbers:read"
  ]
}'
```

```json
{
  "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334",
  "label": "Integração de produção",
  "kind": "integration",
  "scopes": ["messages:write", "messages:read", "numbers:read"],
  "mode": "live",
  "externalId": null,
  "createdAt": "2026-10-28T12:10:44.201Z",
  "expiresAt": null,
  "revokedAt": null,
  "lastUsedAt": null,
  "secret": "hlsn_..."
}
```

Guarde o segredo, que é a chave do seu servidor

```bash
export LUNA_API_KEY="hlsn_..."
```

## Os escopos

A lista é fechada e igual para todas as contas. Estes são os escopos que uma chave de integração pode ter. Os escopos `session:end` e `session:elevate` existem só nas sessões do console.

| Escopo | O que deixa fazer |
| --- | --- |
| `keys:read` | Listar e consultar as chaves da conta. |
| `keys:write` | Criar e revogar chaves. |
| `numbers:read` | Ler números, a saúde deles, as contas de negócio, os links de conexão, a conta e o plano. |
| `numbers:write` | Editar o rótulo de um número, reconectar e desconectar. |
| `messages:read` | Ler mensagens e conversas, e baixar a mídia que chegou. |
| `messages:write` | Enviar mensagens, enviar arquivos de mídia, marcar como lida e mostrar “digitando”. |
| `templates:read` | Listar e consultar templates. |
| `templates:write` | Criar, editar e remover templates, e enviar os arquivos de exemplo. |
| `onboarding:write` | Conectar números: abrir e concluir sessões, reconectar, informar o PIN, e criar e apagar links de conexão. |
| `webhooks:read` | Ler os endpoints de webhook, os tipos de evento e os eventos que a Luna desistiu de entregar. |
| `webhooks:write` | Cadastrar, editar, testar e remover endpoints, trocar o segredo, reenfileirar eventos e pedir que o evento de uma mensagem seja entregue de novo. |

`GET /v1/api-keys/scopes` devolve esta mesma lista pela API: cada escopo com o nome em português (`label`), o que ele permite (`summary`) e `sensitive`, que é `true` nas permissões que dão um poder que exige cuidado (criar chaves e redirecionar o webhook). `GET /v1/api-keys/profiles` devolve os perfis prontos, `agent` (atendimento), `full` (integração completa) e `read_only` (somente leitura), cada um com os escopos que concede. Ao criar a chave, mande `profile` no lugar de `scopes`, um dos dois e nunca os dois: a chave nasce com os escopos que o perfil concede naquele momento, e guarda os escopos, e o perfil fica só como rótulo, em `profile` (nulo quando você escolheu os escopos um a um). Cada chave da lista traz também `status` (`active`, `revoked` ou `expired`, decidido pela API) e `allowedActions` (`revoke` enquanto a chave de integração vale), para você mostrar o botão sem comparar datas. As duas rotas pedem `keys:read`.

> O escopo de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia), no topo de cada operação. Escopo faltando é `403`, e a resposta não diz qual faltou além do que a rota pede.

## Listar e revogar chaves

`GET /v1/api-keys` lista as chaves, com escopos, criação, último uso e revogação. O segredo nunca aparece. Use `kind=integration` para ver só as chaves de integração e esconder as sessões do console. O escopo é `keys:read`.

```bash
curl -X GET "https://api.lunahia.com.br/v1/api-keys?kind=integration" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/api-keys?kind=integration', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/api-keys?kind=integration",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

`POST /v1/api-keys/{id}/revoke` invalida a chave na hora. Repetir a chamada devolve o mesmo resultado, sem erro, e a data da revogação fica registrada. Pede `keys:write` e, para a sessão do console, a janela do passo 3.

```bash
curl -X POST "https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

## Ler a conta e o plano

`GET /v1/account` devolve a conta da credencial: identificador, nome, se o e-mail já foi confirmado e quando a conta foi criada. Não tem escopo próprio: pede `numbers:read`, o mais leve dos escopos de leitura. O campo `operatorEmail` só vem preenchido quando a credencial é uma sessão do console.

```bash
curl -X GET "https://api.lunahia.com.br/v1/account" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/account', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/account",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

```json
{
  "id": "0b5e3c1a-7d42-4f6a-9c18-2e7a1d5b8f90",
  "name": "Sua Empresa",
  "emailConfirmed": true,
  "createdAt": "2026-10-28T11:58:02.114Z",
  "operatorEmail": null
}
```

`PATCH /v1/account` troca o nome da conta. O corpo é `{ "name": "..." }`, de 1 a 120 caracteres, e a resposta é a conta já com o nome novo, no mesmo formato do `GET`. Só a sessão do console faz isto (escopo `session:end`), e a suspensão do plano não bloqueia.

`GET /v1/subscription` devolve o plano, a capacidade de números e quantos estão em uso. Ele tem um guia próprio: [Plano e números](https://lunahia.com.br/docs/plano-e-numeros).

```bash
curl -X GET "https://api.lunahia.com.br/v1/subscription" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/subscription', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/subscription",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

`GET /v1/account/overview` devolve o resumo que uma tela inicial precisa, já decidido pela API: `attention`, a lista do que a conta precisa olhar (cada item com `code`, `severity`, `title`, `message`, `solution`, o `resource` a que se refere, a `action` que resolve e `since`), na ordem em que deve aparecer, com o que está parado primeiro; `checklist`, os quatro primeiros passos (`connect_number`, `create_key`, `add_webhook_endpoint` e `send_message`), cada um com `done` e `doneAt`; e `numbers`, os números por estado de conexão. Pede `numbers:read`, e uma chave restrita a um cliente seu é recusada, porque o resumo é da conta inteira.

## Ver se a plataforma está de pé

`GET /status` não pede chave e não revela dado de nenhuma conta. Ele responde o estado da plataforma, medido a cada poucos minutos por uma mensagem sintética que entra pela mesma porta que a Meta usa e precisa chegar a um destino por HTTPS. O `status` é `ok`, `degraded`, `down` ou `unknown`; sem verificação recente, é `unknown`, e nunca `ok`. `components` separa a entrada (`ingestion`), a entrega (`delivery`) e o horizonte de partições do banco (`partitions`).

```bash
curl -X GET "https://api.lunahia.com.br/status"
```

```js
const res = await fetch('https://api.lunahia.com.br/status', {
  method: 'GET',
});
console.log(res.status, await res.json());
```

```python
import requests

res = requests.get(
    "https://api.lunahia.com.br/status",
    timeout=10,
)
print(res.status_code, res.json())
```

```json
{
  "status": "ok",
  "checkedAt": "2026-10-28T12:05:00.000Z",
  "components": { "ingestion": "ok", "delivery": "ok", "partitions": "ok" },
  "since": "2026-10-27T09:30:00.000Z"
}
```

`GET /healthz` é a sonda mais simples: responde `200` quando o processo está de pé, e não diz nada sobre o envio de mensagens. A página de status do site mostra o mesmo estado, para quem prefere ler a chamar.

## Próximos passos

Com a chave na mão, conecte um número em [Conectar um número](https://lunahia.com.br/docs/conectar-numero) e envie a primeira mensagem em [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos). O contrato de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia).

## Detalhes das rotas deste guia

A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência.

### GET /v1/api-keys

O segredo nunca volta aqui, nem em rota nenhuma. A Luna guarda apenas um resumo criptográfico dele. Se você perdeu a chave, revogue e crie outra.

Use kind=integration para ver só as chaves de integração e esconder as sessões do console.

### POST /v1/api-keys

Dê a ela só os escopos de que ela precisa. Uma chave que só envia mensagem não deveria poder conectar número nem cunhar outras chaves.

externalId, opcional, faz a chave ser de UM cliente seu: ela só lê e envia pelos números com aquele externalId (inclusive os que forem conectados depois com o mesmo rótulo), só cria link de conexão com ele, só vê templates e contas de negócio das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Número de outro cliente seu responde 404, como um que não existe, e rota fora desse conjunto responde 403. Use para dar acesso direto ao cliente do seu cliente, ou para reduzir o estrago de uma chave vazada. O externalId não muda depois da criação.

### POST /v1/api-keys/{id}/revoke

Revogação não apaga a linha. A data fica registrada, para que uma auditoria consiga responder quando o acesso terminou.

### GET /v1/subscription

capacity é quantos números a conta pode manter ativos ao mesmo tempo, e activeNumbers é quantos estão ativos agora. Quando activeNumbers chega a capacity, abrir uma sessão de conexão ou criar um link de conexão responde 409 number_capacity_reached; reconectar um número que já conta não é recusado. Capacidade menor que o uso nunca desconecta ninguém: só recusa o próximo número.

status diz em que pé a conta está. No teste grátis (14 dias, 1 número), trialEndsAt traz o fim e trialDaysLeft traz os dias que faltam, calculados aqui. Com o teste terminado e a conta sem contratação, ou com a conta bloqueada pela Helsen, status é suspended e suspendedReason diz o motivo: o envio e as escritas são recusados, a leitura e o recebimento de mensagens continuam, e o número segue conectado na Meta.

A única grandeza faturável é a quantidade de números que este cliente manteve ativos no período. Nenhum evento da plataforma altera este valor: mensagem, conversa, template, mídia e sessão não entram nesta conta, por caminho nenhum.

O uso da plataforma WhatsApp é cobrado pela Meta, diretamente do negócio final, no método de pagamento que ele cadastra na conta dele. A Helsen não intermedeia esse pagamento, não o adianta e não o repassa.

Ativo significa capacidade configurada, e não apto a enviar agora. Um número aguardando o pagamento do cliente na Meta continua sendo capacidade configurada e continua contando. Um número ativo por três dias conta igual a um ativo o mês inteiro: não há fração de período.

O período é meio-aberto: o início entra, o fim não. inicio e fim vêm juntos ou nenhum dos dois: sem eles, vale o mês corrente em UTC, calculado pela API. Mande os dois quando precisar de uma resposta que não dependa do relógio.

A lista de identificadores traz os números que contaram no período, para que a contagem seja conferível.

### POST /v1/operators/signup

A resposta não traz sessão. Depois do 201, autentique em POST /v1/operators/login com o mesmo e-mail e a mesma senha.

A senha tem no mínimo 12 caracteres, sem exigência de composição. Comprimento protege mais que a mistura obrigatória de símbolos, que só produz senha previsível. Uma senha mais curta responde 400 com o campo password e o mínimo. Essa recusa pode ser dita: a regra é igual para todos e não revela nada de conta nenhuma.

A conta nova entra, lê a documentação, cria e revoga chave de API e integra contra esta API. O que ela ainda não pode é abrir sessão de conexão de número: isso espera a confirmação do e-mail, e nada além dela.

Um e-mail que já tem conta responde o mesmo 201, e o dono do endereço recebe um e-mail dizendo que a conta já existe e como entrar. Responder diferente entregaria de graça a lista de quem tem conta.

### GET /v1/operators/confirm

O link vale por sete dias e é aceito uma única vez. Abrir de novo não desfaz a confirmação, e a conta continua confirmada.

Toda recusa leva ao mesmo endereço, com erro=1. A resposta não diz se o token não existe, se expirou ou se já foi usado, porque distinguir os três entregaria informação sobre uma conta alheia.

Confirmar o e-mail é o que libera a conexão de número: a conta confirmada já pode abrir sessão de conexão.

### POST /v1/operators/password/forgot

A resposta é sempre 202, com o mesmo corpo, exista ou não uma conta com esse e-mail. Dizer qual dos dois entregaria de graça a lista de quem tem conta. O envio acontece depois da resposta, então o tempo também não distingue.

Quando a conta existe, o link vale por uma hora e pode ser aberto uma única vez, e um pedido novo invalida o anterior. Pedidos repetidos para a mesma conta deixam de gerar e-mail depois de alguns por hora, e a resposta continua igual.

O link aponta para a tela de redefinição do console. Quem integra pela API pura conclui com POST /v1/operators/password/reset, levando o token que vem no endereço.

### POST /v1/operators/password/reset

A senha segue a mesma regra do cadastro: no mínimo 12 caracteres, sem exigência de composição. Uma senha fora da regra responde 400 com o campo password e o mínimo, antes de olhar o token.

O token é aceito uma única vez e vale por uma hora. Token desconhecido, malformado, vencido ou já usado responde o mesmo 400, com o mesmo corpo, porque distinguir entregaria informação sobre uma conta alheia.

Trocar a senha encerra todas as sessões do console desse operador. As chaves de API de integração não são sessões e continuam valendo.

### GET /v1/account

Funciona com a sessão do console e com chave de API de integração. Não há escopo próprio para esta leitura: ela pede numbers:read, o mais leve dos escopos de leitura, e uma chave sem nenhum escopo de leitura recebe 403.

operatorEmail é o e-mail do operador, e só existe quando a credencial é uma sessão do console. Uma chave de integração não tem pessoa atrás, e para ela o campo vem null.

### POST /v1/operators/confirmation/resend

Só para a sessão do console: uma chave de API de integração não tem e-mail para receber o link e recebe 403.

Responde 202 nos dois casos. Se a conta já estava confirmada nada é enviado e emailConfirmed vem true; caso contrário vem false e o e-mail saiu. Se o envio falha, responde 503 e vale tentar de novo.

Há um teto de poucos reenvios por hora, por conta, e passado ele a resposta é 429.

### POST /v1/operators/login

A recusa é sempre a mesma, byte a byte. A API não distingue senha errada de conta inexistente, porque distinguir entregaria de graça a lista de quem tem conta.

A sessão não pode criar nem revogar chaves de API. Para isso existe a reautenticação.

Depois de 10 tentativas erradas para o mesmo e-mail em 15 minutos, o login desse e-mail responde 429 com Retry-After até a janela vencer, inclusive com a senha certa. Se esqueceu a senha, use POST /v1/operators/password/forgot.

### POST /v1/operators/step-up

Nenhuma credencial elevada é emitida. Não há segredo novo nesta resposta, nem linha nova no banco: o que muda é um instante gravado na própria sessão, e elevatedUntil é esse instante.

Passadas as duas horas a senha volta a ser pedida, e reabrir a janela exige confirmá-la de novo. Encerrar a sessão encerra a janela junto, sem passo próprio.

Não recebe email: a identidade vem da própria sessão. Assim a senha de um operador nunca eleva a sessão de outro.
