# Chaves

Fonte: https://lunahia.com.br/docs/referencia/chaves

Criar, listar e revogar as credenciais que autenticam as suas chamadas.

### Listar chaves

`GET /v1/api-keys`

As chaves deste cliente, com escopos, perfil, status (active, revoked ou expired), data de criação, último uso, revogação e o que a conta pode fazer com cada uma (allowedActions).

Autenticação: Chave de API. Escopo exigido: `keys:read`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-api-keys

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `kind` | `string` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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-08-07T12:10:44.201Z",
    "expiresAt": null,
    "revokedAt": null,
    "lastUsedAt": "2026-08-10T09:02:18.664Z",
    "status": "active",
    "profile": "agent",
    "allowedActions": [
      "revoke"
    ]
  }
]
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Criar uma chave

`POST /v1/api-keys`

Cunha uma chave nova e devolve o segredo uma única vez. Guarde-o no momento em que recebe, porque não há rota que o devolva depois.

Autenticação: Chave de API. Escopo exigido: `keys:write`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-api-keys

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `label` | `string` | não | 1 a 120 caracteres |
| `scopes` | `array<string>` | não | O que a chave pode fazer, escopo por escopo. Mande scopes ou profile, e nunca os dois: a lista de escopos que cada perfil concede está em GET /v1/api-keys/profiles. · no mínimo 1 itens |
| `profile` | `string` | não | Um perfil pronto no lugar de scopes: agent (atendimento), full (integração completa) ou read_only (somente leitura). A chave nasce com os escopos que o perfil concede no momento da criação, e a lista deles está em GET /v1/api-keys/profiles. · Valores: agent, full, read_only |
| `expiresAt` | `string (date-time)` | não |  |
| `mode` | `string` | não | live (o padrão) é a chave de sempre. test cria uma chave do modo de teste: POST /v1/messages com ela NÃO vai à Meta, não usa número seu e não conta na capacidade do plano; a Luna devolve ao seu webhook eventos simulados, assinados e com test: true. Uma chave de teste só usa POST /v1/messages e POST /v1/test-mode/inbound-messages, e não aceita externalId. Não dá para mudar depois: crie outra. · Valores: live, test |
| `externalId` | `string` | não | O seu identificador para o cliente a que esta chave pertence (1 a 128 caracteres), o mesmo externalId do link de conexão e dos números. Com ele, a chave é de UM cliente seu: só lê e envia pelos números com este externalId (inclusive os conectados depois), só cria link com ele, e não lista nem cria endpoints de webhook nem chaves. Sem ele, a chave é da conta inteira. Não dá para mudar depois: crie outra. · 1 a 128 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/api-keys" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "YOUR_LABEL",
  "scopes": [
    "keys:read"
  ],
  "profile": "agent"
}'
```

#### Respostas

**201**: Criado.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": "YOUR_LABEL",
  "kind": "integration",
  "scopes": [
    "YOUR_SCOPES"
  ],
  "mode": "live",
  "externalId": "YOUR_EXTERNALID",
  "createdAt": "YOUR_CREATEDAT",
  "expiresAt": "YOUR_EXPIRESAT",
  "revokedAt": "YOUR_REVOKEDAT",
  "lastUsedAt": "YOUR_LASTUSEDAT",
  "status": "active",
  "profile": "agent",
  "allowedActions": [
    "revoke"
  ],
  "secret": "YOUR_SECRET"
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Listar os escopos que uma chave pode ter

`GET /v1/api-keys/scopes`

Os escopos que uma chave de integração pode receber, cada um com o nome em português, o que ele permite e se dá um poder que exige cuidado.

Autenticação: Chave de API. Escopo exigido: `keys:read`

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "data": [
    {
      "scope": "messages:write",
      "label": "Enviar mensagens",
      "summary": "Envia mensagens e templates pelos números conectados.",
      "sensitive": false
    },
    {
      "scope": "keys:write",
      "label": "Criar e revogar chaves",
      "summary": "Permite que esta chave crie outras chaves, sem prazo. Dê só a quem precisa.",
      "sensitive": true
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Listar os perfis de chave

`GET /v1/api-keys/profiles`

Os perfis prontos de chave (agent, full e read_only) e os escopos que cada um concede. Em POST /v1/api-keys, profile vale no lugar de scopes.

Autenticação: Chave de API. Escopo exigido: `keys:read`

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "data": [
    {
      "id": "read_only",
      "label": "Somente leitura",
      "summary": "Consulta tudo e não altera nada.",
      "scopes": [
        "keys:read",
        "numbers:read",
        "messages:read",
        "templates:read",
        "webhooks:read"
      ]
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Consultar uma chave

`GET /v1/api-keys/{id}`

Os metadados de uma chave. O segredo não volta, pelo mesmo motivo descrito na listagem.

Autenticação: Chave de API. Escopo exigido: `keys:read`

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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-08-07T12:10:44.201Z",
  "expiresAt": null,
  "revokedAt": null,
  "lastUsedAt": "2026-08-10T09:02:18.664Z",
  "status": "active",
  "profile": "agent",
  "allowedActions": [
    "revoke"
  ]
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Revogar uma chave

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

Invalida a chave imediatamente. A operação é idempotente, então revogar de novo devolve o mesmo resultado, sem erro.

Autenticação: Chave de API. Escopo exigido: `keys:write`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-api-keys-id-revoke

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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-08-07T12:10:44.201Z",
  "expiresAt": null,
  "revokedAt": null,
  "lastUsedAt": "2026-08-10T09:02:18.664Z",
  "status": "active",
  "profile": "agent",
  "allowedActions": [
    "revoke"
  ]
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```
