# Keys

Fonte: https://lunahia.com.br/en/docs/reference/keys

Create, list and revoke the credentials that authenticate your calls.

### List API keys

`GET /v1/api-keys`

This customer's keys, with scopes, profile, status (active, revoked or expired), creation date, last use, revocation and what the account can do with each one (allowedActions).

Authentication: API key. Required scope: `keys:read`

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-api-keys

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `string` | no |  |

#### Code examples

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

#### Responses

**200**: Success.

```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**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### Create an API key

`POST /v1/api-keys`

Mints a new key and returns the secret exactly once. Store it the moment you receive it, because no route will return it again.

Authentication: API key. Required scope: `keys:write`

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-api-keys

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | no | 1 to 120 characters |
| `scopes` | `array<string>` | no | 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. · at least 1 items |
| `profile` | `string` | no | 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. · Values: agent, full, read_only |
| `expiresAt` | `string (date-time)` | no |  |
| `mode` | `string` | no | 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. · Values: live, test |
| `externalId` | `string` | no | 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 to 128 characters |

#### Code examples

```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"
}'
```

#### Responses

**201**: Created.

```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**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

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

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### List the scopes a key can have

`GET /v1/api-keys/scopes`

The scopes an integration key can receive, each with its name in Portuguese, what it allows and whether it gives a power that calls for care.

Authentication: API key. Required scope: `keys:read`

#### Code examples

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

#### Responses

**200**: Success.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### List the key profiles

`GET /v1/api-keys/profiles`

The ready-made key profiles (agent, full and read_only) and the scopes each one grants. In POST /v1/api-keys, profile stands in for scopes.

Authentication: API key. Required scope: `keys:read`

#### Code examples

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

#### Responses

**200**: Success.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### Read one API key

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

One key's metadata. The secret does not come back, for the reason described on the listing route.

Authentication: API key. Required scope: `keys:read`

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Code examples

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

#### Responses

**200**: Success.

```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**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

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

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### Revoke an API key

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

Invalidates the key immediately. The operation is idempotent, so revoking again returns the same result without an error.

Authentication: API key. Required scope: `keys:write`

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-api-keys-id-revoke

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Code examples

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

#### Responses

**200**: Success.

```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**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

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

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```
