# Console and public pages

Fonte: https://lunahia.com.br/en/docs/reference/console-and-public-pages

Routes the Luna console and the public connection link page use: sign-up, login, session and completion of the flow. You normally do not need them. They exist here because the console is a client of this same API, with no privileged route.

### Read the connect link (customer page)

`GET /v1/public/onboarding-links/{token}`

For the page your customer opens. Returns the name of the account that asked for the connection, the link status, and the public identifiers of the Meta app that the connection window uses. Nothing else about your account comes out here.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-get-v1-public-onboarding-links-token

#### Path parameters

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

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN"
```

#### Responses

**200**: Success.

```json
{
  "accountName": "YOUR_ACCOUNTNAME",
  "displayName": "YOUR_DISPLAYNAME",
  "status": "open",
  "expiresAt": "YOUR_EXPIRESAT",
  "metaAppId": "YOUR_METAAPPID",
  "metaConfigId": "YOUR_METACONFIGID",
  "sdkVersion": "YOUR_SDKVERSION",
  "redirectUrl": "YOUR_REDIRECTURL",
  "reconnect": true
}
```

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

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

### Open the connection session through the link

`POST /v1/public/onboarding-links/{token}/sessions`

Opens the session that Meta's window fills in, for the account that owns the link. It is the same opening as POST /v1/onboarding/sessions, through the token's door. On a reconnection link (created with numberId), the session is born bound to the number's account, as in POST /v1/onboarding/reconnect.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions

#### Path parameters

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

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions"
```

#### Responses

**201**: Created.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "configId": "YOUR_CONFIGID",
  "sdkVersion": "YOUR_SDKVERSION",
  "csrfState": "YOUR_CSRFSTATE",
  "expiresAt": "YOUR_EXPIRESAT"
}
```

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

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

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "account_at_capacity",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "A conta que pediu esta conexão atingiu o máximo de números. Avise quem enviou este link: assim que ela abrir uma vaga, ele poderá enviar um link novo."
}
```

**410**: The connect link expired or was already used. The error field says which of the two.

```json
{
  "error": "link_expired",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este link venceu. Peça um novo a quem enviou este."
}
```

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

### Complete the connection through the link

`POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/complete`

Exchanges the code from Meta's window for access to the customer's account. It is the same completion as POST /v1/onboarding/sessions/{id}/complete, through the token's door, and the same warning holds: the code lasts 30 seconds, so call it the moment it arrives.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions-sessionid-complete

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes |  |
| `sessionId` | `string` | yes |  |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | yes |  |
| `csrfState` | `string` | yes |  |
| `wabaId` | `string \| null` | no |  |
| `phoneNumberId` | `string \| null` | no |  |
| `businessId` | `string \| null` | no |  |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/complete" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "YOUR_CODE",
  "csrfState": "YOUR_CSRFSTATE"
}'
```

#### Responses

**200**: Success.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "terminal": true,
  "motivo": "YOUR_MOTIVO",
  "podeRetentar": true,
  "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "returnUrl": "YOUR_RETURNURL"
}
```

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

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

**410**: The connect link expired or was already used. The error field says which of the two.

```json
{
  "error": "link_used",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este."
}
```

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

### Report an abandoned or failed flow through the link

`POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon`

Telemetry about what happened in Meta's window when the customer did not complete. It is the same report as POST /v1/onboarding/sessions/{id}/abandon, through the token's door, and it only applies to a session opened by this same link.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions-sessionid-abandon

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes |  |
| `sessionId` | `string` | yes |  |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrfState` | `string` | yes |  |
| `currentStep` | `string \| null` | no | 1 to 120 characters |
| `errorCode` | `integer \| null` | no |  |
| `errorMessage` | `string \| null` | no |  |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/abandon" \
  -H "Content-Type: application/json" \
  -d '{
  "csrfState": "YOUR_CSRFSTATE"
}'
```

#### Responses

**200**: Success.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "abandonedAtStep": "YOUR_ABANDONEDATSTEP"
}
```

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

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

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

### Create an account

`POST /v1/operators/signup`

Creates the account and its first operator, in a single call and with no credential.

Authentication: Public, no key

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | up to 254 characters |
| `password` | `string` | yes | 12 to 512 characters |
| `tenantName` | `string` | yes | 1 to 120 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/signup" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br",
  "password": "YOUR_PASSWORD",
  "tenantName": "YOUR_TENANTNAME"
}'
```

#### Responses

**201**: Created.

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

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

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

### Confirm an account's email

`GET /v1/operators/confirm`

Destination of the link sent by email when the account is created. It answers with a redirect to the console, and not with JSON, because a person in a browser is what opens it.

Authentication: Public, no key

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

#### Query parameters

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

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/operators/confirm"
```

#### Responses

**200**: Success.

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

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

### Ask for a password reset

`POST /v1/operators/password/forgot`

Asks for a link to choose a new password. It takes only the account email.

Authentication: Public, no key

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | up to 254 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br"
}'
```

#### Responses

**202**: Accepted: the request was recorded and will be processed.

```json
{
  "accepted": true
}
```

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

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

### Choose a new password

`POST /v1/operators/password/reset`

Changes the operator's password from the token in the link sent by email, and answers 204.

Authentication: Public, no key

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | up to 512 characters |
| `password` | `string` | yes | 12 to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "YOUR_TOKEN",
  "password": "YOUR_PASSWORD"
}'
```

#### Responses

**204**: No content: the operation was done and the response has no body.

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

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

### Check the reset link

`POST /v1/operators/password/reset/check`

Answers 204 when the link token is still valid and 400 when it is not, without consuming it. Lets the screen warn before the person types the new password.

Authentication: Public, no key

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | up to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset/check" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "YOUR_TOKEN"
}'
```

#### Responses

**204**: No content: the operation was done and the response has no body.

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

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

### Read the password rule

`GET /v1/public/password-policy`

The minimum length of an operator password, the same at signup, reset and change. It asks for no credential.

Authentication: Public, no key

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/password-policy"
```

#### Responses

**200**: Success.

```json
{
  "minLength": 12
}
```

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

### Change the password

`POST /v1/operators/password/change`

Changes the password of the operator behind the presented session, checking the current password, and answers 204. The operator's other sessions are ended and the presented one stays valid. A wrong current password, or a credential with no operator (an integration key), answers 401.

Authentication: API key. Required scope: `session:elevate`

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currentPassword` | `string` | yes | A senha de hoje do operador da sessão. · up to 512 characters |
| `newPassword` | `string` | yes | A senha nova, pela mesma regra do cadastro (GET /v1/public/password-policy diz o mínimo). · 12 to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/change" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "currentPassword": "YOUR_CURRENTPASSWORD",
  "newPassword": "YOUR_NEWPASSWORD"
}'
```

#### Responses

**204**: No content: the operation was done and the response has no body.

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

### Resend the confirmation email

`POST /v1/operators/confirmation/resend`

Sends the confirmation link again to the email of the operator behind the session, and invalidates the previous link if it had not been opened. The new link is valid for seven days and is accepted a single time.

Authentication: API key. Required scope: `session:end`

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

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/confirmation/resend" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**202**: Accepted: the request was recorded and will be processed.

```json
{
  "emailConfirmed": 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."
}
```

### Authenticate an operator

`POST /v1/operators/login`

Exchanges email and password for an eight hour session credential, used by the web console.

Authentication: Public, no key

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | 1 to 254 characters |
| `password` | `string` | yes | 1 to 512 characters |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "operatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "YOUR_TOKEN",
  "expiresAt": "YOUR_EXPIRESAT",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

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

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

### Re-authenticate for a sensitive action

`POST /v1/operators/step-up`

Confirms the password of the operator behind the session presented, and opens a two hour window in which that same session can create and revoke API keys.

Authentication: API key. Required scope: `session:elevate`

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | `string` | yes | 1 to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/step-up" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "YOUR_PASSWORD"
}'
```

#### Responses

**200**: Success.

```json
{
  "elevatedUntil": "YOUR_ELEVATEDUNTIL",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

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

### Read the presented session

`GET /v1/operators/session`

When the presented credential expires, until when the elevation opened by POST /v1/operators/step-up lasts (null with no elevation or with the window closed) and the scopes it has now. It reads only the credential itself: the identifier comes from authentication and never from the path.

Authentication: API key. Required scope: `session:end`

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "expiresAt": "2026-11-03T20:00:00.000Z",
  "elevatedUntil": "2026-11-03T14:30:00.000Z",
  "scopes": [
    "numbers:read",
    "session:end",
    "session:elevate",
    "keys:write"
  ]
}
```

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

### End the session

`POST /v1/operators/logout`

Revokes the credential presented, and only it. The identifier comes from the authentication itself and never from the body, so this route cannot revoke someone else's key.

Authentication: API key. Required scope: `session:end`

#### Code examples

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

#### Responses

**204**: No content: the operation was done and the response has no body.

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