# Account and keys

Fonte: https://lunahia.com.br/en/docs/account-and-keys

Everything the console does with your account can also be done through the API, because the console is a client of it. This guide shows the whole path: sign up, log in, create a key, use the scopes, revoke, and read the account, the plan and the state of the platform.

## How the API authenticates

Every integration route asks for a key in the `Authorization` header, in the form `Bearer hlsn_...`. The key carries scopes: each route demands its own, and a key without the scope gets `403`. With no key, or with an invalid or revoked one, the answer is `401`.

There are two kinds of credential. The **integration key** is your server’s: it is valid until revoked. The **session** is the console’s: it lasts eight hours, comes from the login, and cannot create or revoke keys on its own. To create a key, the session confirms the password first (step 3 below).

## 1. Sign up

`POST /v1/operators/signup` creates the account and its first operator in a single call, with no credential. The password is at least 12 characters, and whoever builds the screen reads that minimum at `GET /v1/public/password-policy` (`{ "minLength": 12 }`, no credential) instead of copying the number. The answer is `201` and carries no session: the next step is to log in.

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

Luna sends an email with a confirmation link. It is valid for seven days and accepted once. The account already reads the documentation and creates keys before confirming, but only a confirmed account opens a number connection session. If the email did not arrive, `POST /v1/operators/confirmation/resend` sends it again (only with the console session, and there is a ceiling of a few resends per hour).

## 2. Log in

`POST /v1/operators/login` exchanges email and password for an eight-hour session credential. The `token` field is the `Bearer` of the next calls in this guide that use the session. The refusal is always the same, wrong password or no such account.

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

Keep the session token

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

To change the password knowing the current one, without going through "Forgot my password", use `POST /v1/operators/password/change` with the session and the body `{ "currentPassword": "...", "newPassword": "..." }`. The answer is `204`. The new password follows the same rule as signup, the operator's other sessions are ended and the one that asked for the change stays valid. A wrong current password answers `401`, and there is a ceiling on attempts per session.

## 3. Confirm the password

Creating and revoking a key is a sensitive action. `POST /v1/operators/step-up` confirms the password of the session’s operator and opens a two-hour window in which that same session can create and revoke keys. The answer carries `elevatedUntil`, the end of the window, and in `scopes` what the window lends the session (`keys:write`). After the two hours, the password is asked again.

With the session from step 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"]
}
```

To know whether the window is still open without asking for the password needlessly, read `GET /v1/operators/session` with the session: `expiresAt` is the end of the session, `elevatedUntil` is the end of the window (null with no window or with it closed) and `scopes` are the scopes the session has now. It asks for the `session:end` scope, which the console session already has.

## 4. Create a key

`POST /v1/api-keys` creates the key. Ask only for the scopes it needs: a key that only sends messages should not be able to connect a number or create other keys. With `externalId`, the key belongs to ONE of your customers and sees only what is theirs. With `mode: "test"`, the key is a test key: it sends without going to Meta, and only uses two routes (see [Test mode](https://lunahia.com.br/en/docs/test-mode)). The answer carries the `secret` field **exactly once**: no route returns it afterwards, and whoever loses it revokes the key and creates another.

With the session, inside the window from step 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_..."
}
```

Keep the secret, which is your server’s key

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

## The scopes

The list is closed and the same for every account. These are the scopes an integration key can have. The `session:end` and `session:elevate` scopes exist only on console sessions.

| Scope | What it allows |
| --- | --- |
| `keys:read` | List and read the account’s keys. |
| `keys:write` | Create and revoke keys. |
| `numbers:read` | Read numbers, their health, the business accounts, the connection links, the account and the plan. |
| `numbers:write` | Edit a number’s label, reconnect and disconnect. |
| `messages:read` | Read messages and conversations, and download the media that arrived. |
| `messages:write` | Send messages, upload media files, mark as read and show “typing”. |
| `templates:read` | List and read templates. |
| `templates:write` | Create, edit and delete templates, and upload the sample files. |
| `onboarding:write` | Connect numbers: open and complete sessions, reconnect, give the PIN, and create and delete connection links. |
| `webhooks:read` | Read the webhook endpoints, the event types and the events Luna gave up delivering. |
| `webhooks:write` | Register, edit, test and delete endpoints, rotate the secret, requeue events and ask for a message’s event to be delivered again. |

`GET /v1/api-keys/scopes` returns this same list through the API: each scope with its name in Portuguese (`label`), what it allows (`summary`) and `sensitive`, which is `true` for the permissions that give a power that calls for care (creating keys and redirecting the webhook). `GET /v1/api-keys/profiles` returns the ready-made profiles, `agent` (support agent), `full` (full integration) and `read_only`, each with the scopes it grants. When creating the key, send `profile` in place of `scopes`, one of the two and never both: the key is born with the scopes the profile grants at that moment, and stores the scopes, while the profile stays only as a label, in `profile` (null when you picked the scopes one by one). Each key in the list also carries `status` (`active`, `revoked` or `expired`, decided by the API) and `allowedActions` (`revoke` while the integration key is valid), so you can show the button without comparing dates. Both routes ask for `keys:read`.

> Each route’s scope is in the [API reference](https://lunahia.com.br/en/docs/reference), at the top of each operation. A missing scope is `403`, and the answer does not say which one is missing beyond what the route asks.

## List and revoke keys

`GET /v1/api-keys` lists the keys, with scopes, creation, last use and revocation. The secret never shows. Use `kind=integration` to see only integration keys and hide console sessions. The scope is `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` invalidates the key at once. Repeating the call returns the same result, without error, and the revocation date stays on record. It needs `keys:write` and, for the console session, the window from step 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())
```

## Read the account and the plan

`GET /v1/account` returns the credential’s account: identifier, name, whether the email is already confirmed and when the account was created. It has no scope of its own: it asks for `numbers:read`, the lightest of the read scopes. The `operatorEmail` field is filled only when the credential is a console session.

```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` changes the account name. The body is `{ "name": "..." }`, 1 to 120 characters, and the answer is the account with the new name, in the same shape as the `GET`. Only the console session does this (scope `session:end`), and plan suspension does not block it.

`GET /v1/subscription` returns the plan, the number capacity and how many are in use. It has a guide of its own: [Plan and numbers](https://lunahia.com.br/en/docs/plan-and-numbers).

```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` returns the summary a home screen needs, already decided by the API: `attention`, the list of what the account needs to look at (each item with `code`, `severity`, `title`, `message`, `solution`, the `resource` it refers to, the `action` that fixes it and `since`), in the order it should appear, with what is stopped first; `checklist`, the four first steps (`connect_number`, `create_key`, `add_webhook_endpoint` and `send_message`), each with `done` and `doneAt`; and `numbers`, the numbers by connection state. It asks for `numbers:read`, and a key restricted to one of your customers is refused, because the summary belongs to the whole account.

## See whether the platform is up

`GET /status` needs no key and reveals no account data. It answers the state of the platform, measured every few minutes by a synthetic message that enters through the same door Meta uses and has to reach a destination over HTTPS. The `status` is `ok`, `degraded`, `down` or `unknown`; with no recent check, it is `unknown`, and never `ok`. `components` separates intake (`ingestion`), delivery (`delivery`) and the database partition horizon (`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` is the simplest probe: it answers `200` when the process is up, and says nothing about sending messages. The site’s status page shows the same state, for whoever prefers to read over calling.

## Next steps

With the key in hand, connect a number in [Connect a number](https://lunahia.com.br/en/docs/connect-a-number) and send the first message in [Quickstart](https://lunahia.com.br/en/docs/quickstart). Each route’s contract is in the [API reference](https://lunahia.com.br/en/docs/reference).

## Route details for this guide

The [API reference](https://lunahia.com.br/en/docs/reference) says how to call each route, in a few lines. What explains the reason for each decision, the edge cases and the warnings is here, in the order of the reference.

### GET /v1/api-keys

The secret never comes back here, or from any other route. Luna stores only a cryptographic digest of it. If you lost a key, revoke it and create another.

Use kind=integration to see only integration keys and hide console sessions.

### POST /v1/api-keys

Give it only the scopes it needs. A key that just sends messages should not be able to connect numbers or mint other keys.

externalId, optional, makes the key belong to ONE of your customers: it only reads and sends through the numbers with that externalId (including the ones connected later with the same label), only creates connect links with it, only sees templates and business accounts of the WABAs of those numbers, and neither lists nor creates webhook endpoints or keys. Another customer's number answers 404, like one that does not exist, and a route outside that set answers 403. Use it to give your customer's customer direct access, or to limit the damage of a leaked key. The externalId cannot be changed after creation.

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

Revoking does not delete the row. The date stays on record, so an audit can answer when the access ended.

### GET /v1/subscription

capacity is how many numbers the account can keep active at the same time, and activeNumbers is how many are active right now. When activeNumbers reaches capacity, opening a connection session or creating a connect link answers 409 number_capacity_reached; reconnecting a number that already counts is not refused. A capacity lower than the usage never disconnects anyone: it only refuses the next number.

status says where the account stands. In the free trial (14 days, 1 number), trialEndsAt carries the end and trialDaysLeft carries the days left, computed here. With the trial over and the account not contracted, or with the account blocked by Helsen, status is suspended and suspendedReason gives the reason: sending and writes are refused, reading and receiving messages keep working, and the number stays connected at Meta.

The only billable quantity is how many numbers this customer kept active during the period. No platform event changes this value: messages, conversations, templates, media and sessions do not enter this calculation by any path.

Use of the WhatsApp platform is billed by Meta, directly to the end business, on the payment method it registers in its own account. Helsen does not intermediate that payment, does not advance it and does not pass it through.

Active means configured capacity, not able to send right now. A number waiting on the customer's payment with Meta is still configured capacity and still counts. A number active for three days counts the same as one active all month: there is no proration.

The period is half-open: the start is included, the end is not. inicio and fim come together or not at all: without them, the current month in UTC applies, computed by the API. Send both when you need an answer that does not depend on the clock.

The identifier list carries the numbers that counted in the period, so the count can be checked.

### POST /v1/operators/signup

The response carries no session. After the 201, authenticate at POST /v1/operators/login with the same email and password.

The password is at least 12 characters, with no composition requirement. Length protects more than a mandatory mix of symbols, which only produces predictable passwords. A shorter password answers 400 with the password field and the minimum. That one is safe to say: the rule is the same for everyone and reveals nothing about any account.

The new account signs in, reads the documentation, creates and revokes API keys, and integrates against this API. What it cannot do yet is open a number connection session: that waits on the email confirmation, and on nothing else.

An email that already has an account gets the same 201, and the owner of the address receives an email saying the account already exists and how to sign in. Answering differently would hand over the list of who has an account for free.

### GET /v1/operators/confirm

The link is valid for seven days and is accepted exactly once. Opening it again does not undo the confirmation, and the account stays confirmed.

Every rejection leads to the same address, with erro=1. The response does not say whether the token does not exist, expired, or was already used, because distinguishing the three would hand over information about someone else's account.

Confirming the email is what unlocks connecting a number: a confirmed account can already open a connection session.

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

The answer is always 202, with the same body, whether or not an account exists with that email. Saying which one it is would hand over the list of who has an account for free. The email is sent after the response, so timing does not tell them apart either.

When the account exists, the link is valid for one hour and can be opened a single time, and a new request invalidates the previous one. Repeated requests for the same account stop producing email after a few per hour, and the answer stays the same.

The link points to the console's reset screen. If you integrate through the bare API, finish with POST /v1/operators/password/reset, carrying the token that is in the address.

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

The password follows the same rule as signup: at least 12 characters, with no composition requirement. A password outside the rule answers 400 with the password field and the minimum, before the token is looked at.

The token is accepted a single time and is valid for one hour. An unknown, malformed, expired or already used token answers the same 400, with the same body, because telling them apart would hand over information about someone else's account.

Changing the password ends every console session of that operator. Integration API keys are not sessions and keep working.

### GET /v1/account

It works with a console session and with an integration API key. There is no scope of its own for this read: it asks for numbers:read, the lightest of the read scopes, and a key with no read scope at all gets 403.

operatorEmail is the operator's email, and it only exists when the credential is a console session. An integration key has no person behind it, and for it the field comes back null.

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

Console session only: an integration API key has no email to receive the link and gets 403.

It answers 202 in both cases. If the account was already confirmed nothing is sent and emailConfirmed is true; otherwise it is false and the email went out. If sending fails it answers 503 and it is worth trying again.

There is a ceiling of a few resends per hour, per account, and past it the answer is 429.

### POST /v1/operators/login

The rejection is always identical, byte for byte. The API does not distinguish a wrong password from a nonexistent account, because distinguishing them would hand over the list of who has an account for free.

The session cannot create or revoke API keys. Re-authentication exists for that.

After 10 wrong attempts for the same email within 15 minutes, login for that email answers 429 with Retry-After until the window ends, even with the right password. If you forgot the password, use POST /v1/operators/password/forgot.

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

No elevated credential is issued. There is no new secret in this response and no new row in the database: what changes is a timestamp recorded on the session itself, and elevatedUntil is that timestamp.

After two hours the password is required again, and reopening the window means confirming it once more. Ending the session ends the window with it, with no separate step.

It takes no email: the identity comes from the session itself. That way one operator's password never elevates another operator's session.
