Registro e verificação

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

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`

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.

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.

# 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):

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. Para contas que já existem, use login. Sem 2FA:

# 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):

curl https://api.notifique.dev/v1/platform/workspaces \
  -H "Authorization: Bearer <sessionToken>"

Passo A — e-mail e senha:

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:

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:

{
  "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

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

Nunca logue apiKey ou verificationToken em stdout
Trate retryAfter antes de reenviar OTP
Use createApiKey: false se só precisa de sessionToken
Após o onboarding, crie chaves restritas — Escopos
Segundo workspace: Workspaces

Próximo: Quick start · Billing

Guias simples

Conheça mais

Workspaces

OAuth 2.1

IA e no-code

BYOK

Changelog

Platform API

Conta

API Keys

Billing

Créditos

Equipe

Metadados

OAuth

Webhooks

Entregas

Logs

Workspaces

Registro e verificação

O que é o `verificationToken`?

Credenciais no fluxo

Fluxo completo para agente ou script

1. Primeira conta e primeiro workspace

2. Criar um segundo workspace

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

Survey de onboarding

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

Boas práticas

​O que é o verificationToken?

​Credenciais no fluxo

​Fluxo completo para agente ou script

​1. Primeira conta e primeiro workspace

​2. Criar um segundo workspace

​3. Login e API key no workspace certo

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

​Registro (POST /v1/platform/register)

​Survey de onboarding

​Verificação (POST /v1/platform/verify)

​Login (POST /v1/platform/login)

​Boas práticas

O que é o `verificationToken`?

Credenciais no fluxo

Fluxo completo para agente ou script

1. Primeira conta e primeiro workspace

2. Criar um segundo workspace

3. Login e API key no workspace certo

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

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

Survey de onboarding

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

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

Boas práticas