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.
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"
}'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());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()){
"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.
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"
}'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());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()){
"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"
]
}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.
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"
}'{
"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). The answer carries the secret field exactly once: no route returns it afterwards, and whoever loses it revokes the key and creates another.
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"
]
}'{
"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_..."
}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.
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.
curl -X GET "https://api.lunahia.com.br/v1/api-keys?kind=integration" \
-H "Authorization: Bearer $LUNA_API_KEY"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());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.
curl -X POST "https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke" \
-H "Authorization: Bearer $LUNA_API_KEY"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());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.
curl -X GET "https://api.lunahia.com.br/v1/account" \
-H "Authorization: Bearer $LUNA_API_KEY"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());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()){
"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.
curl -X GET "https://api.lunahia.com.br/v1/subscription" \
-H "Authorization: Bearer $LUNA_API_KEY"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());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).
curl -X GET "https://api.lunahia.com.br/status"const res = await fetch('https://api.lunahia.com.br/status', {
method: 'GET',
});
console.log(res.status, await res.json());import requests
res = requests.get(
"https://api.lunahia.com.br/status",
timeout=10,
)
print(res.status_code, res.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 and send the first message in Quickstart. Each route’s contract is in the API reference.
Route details for this guide#
The API 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.