> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Registro e verificação

> Crie conta, confirme o telefone por OTP e obtenha a API key sem abrir o painel.

<Tip>
  Registro + OTP é a **porta de entrada**: sem verificar o telefone você não recebe a `apiKey` que abre o resto da API.
</Tip>

A Platform API separa **autenticação de conta** (registro/login + OTP) da **autenticação de API** (`apiKey`). Entenda cada etapa antes de automatizar onboarding com IA ou scripts.

## O que é o `verificationToken`?

É um **JWT temporário (\~15 minutos)** que a API devolve quando precisa de um segundo passo antes de liberar sessão ou API key. **Não** é a API key e **não** serve para enviar mensagens.

| Origem                       | Quando aparece                                                 | Próximo passo                                                      |
| ---------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
| `POST /v1/platform/register` | Após cadastrar conta; OTP enviado ao telefone                  | `POST /v1/platform/verify` com `code` (6 dígitos WhatsApp/SMS)     |
| `POST /v1/platform/login`    | Conta com **2FA ativo**; resposta `requiresSecondFactor: true` | **Outro** `POST /v1/platform/login` com `totpCode` ou `backupCode` |

<Warning>
  `POST /v1/platform/verify` confirma só o **OTP de telefone do registro**. Código TOTP do app autenticador (2FA) vai em **`POST /login`**, não em `verify`.
</Warning>

## Credenciais no fluxo

| Etapa                          | Credencial                       | Validade          | Uso                                                 |
| ------------------------------ | -------------------------------- | ----------------- | --------------------------------------------------- |
| Após `register`                | `verificationToken` (onboarding) | \~15 min          | `POST /v1/platform/verify` + código do SMS/WhatsApp |
| Após `login` com 2FA pendente  | `verificationToken` (login\_2fa) | \~15 min          | `POST /v1/platform/login` + `totpCode`              |
| Após `verify` (registro)       | `apiKey` + `workspaceId`         | permanente        | Toda a API v1                                       |
| Login sem 2FA                  | `sessionToken`                   | sessão (\~7 dias) | `GET /v1/platform/me`, billing com sessão           |
| Login com `createApiKey: true` | nova `apiKey` + `workspaceId`    | permanente        | API v1 no workspace escolhido                       |

***

## Fluxo completo para agente ou script

### 1. Primeira conta e primeiro workspace

O **primeiro workspace** é criado automaticamente quando o telefone é verificado — você não chama `POST /v1/workspaces` nesse momento.

```bash theme={null}
# 1a. Registrar
curl -X POST https://api.notifique.dev/v1/platform/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@empresa.com",
    "password": "SenhaSegura123!",
    "phone": "5511999999999",
    "onboardingSurvey": {
      "rolePersona": "developer",
      "plannedChannels": ["whatsapp", "email"]
    }
  }'
# → data.verificationToken (guarde), OTP no telefone

# 1b. Verificar telefone
curl -X POST https://api.notifique.dev/v1/platform/verify \
  -H "Content-Type: application/json" \
  -d '{
    "verificationToken": "<token do register>",
    "code": "123456"
  }'
# → data.apiKey, data.workspaceId (primeiro workspace), data.user
```

Guarde `apiKey` e `workspaceId` — a chave **não** é exibida de novo.

### 2. Criar um segundo workspace

Com a API key do primeiro workspace (escopo `workspace:create` ou escopos vazios no onboarding):

```bash theme={null}
curl -X POST https://api.notifique.dev/v1/workspaces \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homologação",
    "color": "#3B82F6"
  }'
# → data.id = novo workspaceId (ex.: clws_02H...)
```

Limite de slots do plano → **403** `WORKSPACE_SLOTS_LIMIT_REACHED`.

### 3. Login e API key no workspace certo

Para contas que **já existem**, use login. Sem 2FA:

```bash theme={null}
# Sessão + nova API key no workspace de homologação
curl -X POST https://api.notifique.dev/v1/platform/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@empresa.com",
    "password": "SenhaSegura123!",
    "createApiKey": true,
    "workspaceId": "clws_02H..."
  }'
# → sessionToken, apiKey, workspaceId, user.workspaces (lista com roles)
```

* `workspaceId` opcional: se omitido com `createApiKey: true`, a API usa o workspace OWNER mais recente.
* Só workspaces onde você é **OWNER** ou **ADMIN** aceitam nova chave via login.
* `createApiKey: false` → só `sessionToken` (útil para billing no browser ou `GET /v1/platform/workspaces`).

Listar todos os workspaces da conta (sessão):

```bash theme={null}
curl https://api.notifique.dev/v1/platform/workspaces \
  -H "Authorization: Bearer <sessionToken>"
```

### 4. Login com 2FA (quando ativo no painel)

**Passo A** — e-mail e senha:

```bash theme={null}
curl -X POST https://api.notifique.dev/v1/platform/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@empresa.com",
    "password": "SenhaSegura123!"
  }'
# → requiresSecondFactor: true, verificationToken (novo JWT, purpose login_2fa)
```

**Passo B** — mesmo endpoint, com token do passo A + TOTP do app:

```bash theme={null}
curl -X POST https://api.notifique.dev/v1/platform/login \
  -H "Content-Type: application/json" \
  -d '{
    "verificationToken": "<token do passo A>",
    "totpCode": "482193",
    "createApiKey": true,
    "workspaceId": "clws_02H..."
  }'
```

Alternativa: `backupCode` em vez de `totpCode`.

***

## Registro (`POST /v1/platform/register`)

Campos principais:

* `email`, `password` (mín. 10 caracteres), `phone` (internacional)
* `name` — opcional
* `onboardingSurvey` — persona e canais (enums fixos)
* `referralCode` — opcional

Resposta: `verificationToken`, `message`, `retryAfter`. Em dev pode incluir `devCode`.

### Survey de onboarding

| Campo                                      | Obrigatório | Valores / notas                                                                                                                   |
| ------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `rolePersona`                              | sim         | `developer`, `company`, `store`, `marketing`, `autonomous`, `other`                                                               |
| `plannedChannels`                          | sim         | 1–11 itens: `whatsapp`, `telegram`, `sms`, `email`, `push`, `rcs`, `instagram`, `voice`, `widget-chat`, `pipeline`, `automations` |
| `primaryGoal`                              | opcional    | `attend_customers`, `automate`, `campaigns`, `api`, `team`, `exploring`                                                           |
| `companyName`, `websiteUrl`, `description` | opcional    | validação de site quando informado                                                                                                |

## Verificação (`POST /v1/platform/verify`)

Só para **OTP de telefone** após `register`:

```json theme={null}
{
  "verificationToken": "<JWT retornado no register>",
  "code": "123456"
}
```

Sucesso: `apiKey`, `workspaceId` (workspace inicial), `user`.

| Código                       | Situação                                               |
| ---------------------------- | ------------------------------------------------------ |
| `VERIFICATION_TOKEN_INVALID` | Token expirado ou de outro fluxo (ex.: token 2FA aqui) |
| `OTP_INVALID`                | Código incorreto (`attemptsRemaining`)                 |
| `OTP_INVALID_OR_EXPIRED`     | Código expirado — novo OTP exige novo `register`       |
| `OTP_MAX_ATTEMPTS`           | Muitas tentativas                                      |

## Login (`POST /v1/platform/login`)

Três modos no **mesmo endpoint**:

| Modo        | Body                                             | Resposta                                 |
| ----------- | ------------------------------------------------ | ---------------------------------------- |
| Credenciais | `email` + `password`                             | `sessionToken` ou `requiresSecondFactor` |
| 2FA         | `verificationToken` + `totpCode` ou `backupCode` | `sessionToken` (+ `apiKey` se pedido)    |
| + API key   | `createApiKey: true`, opcional `workspaceId`     | também `apiKey` e `workspaceId`          |

## Boas práticas

1. **Nunca** logue `apiKey` ou `verificationToken` em stdout
2. Trate `retryAfter` antes de reenviar OTP
3. Use `createApiKey: false` se só precisa de `sessionToken`
4. Após o onboarding, crie chaves restritas — [Escopos](/platform-api/como-funciona/escopos-api-key)
5. Segundo workspace: [Workspaces](/platform-api/como-funciona/workspaces)

Próximo: [Quick start](/platform-api/como-funciona/quick-start) · [Billing](/platform-api/como-funciona/billing)