Autenticação do Dashboard

Estes endpoints alimentam o login no Dashboard. Um usuário faz login como usuário de merchant ou de organization, recebe uma sessão e a apresenta como token bearer em cada chamada subsequente ao Dashboard. Eles também cobrem a manutenção rotineira de uma sessão: renovar um token prestes a expirar, alterar ou redefinir uma senha, listar as associações que um usuário possui e trocar qual é a organization ativa.

Isto é diferente da autenticação por chave de API. As chamadas de máquina a máquina para a API pública usam chaves sk_…/pk_… e nunca tocam nestes endpoints; estes existem para o Dashboard humano, baseado em navegador. Aceitar um convite do Dashboard também acontece aqui — consulte Convites para conhecer o ciclo de vida do convite.

A resposta de login

Retornado pelos endpoints de listagem e recuperação desta página.

Endpoints

POST/api/v1/auth/change-password

Permite que usuários com senhas temporárias alterem sua senha antes de fazer login. Obrigatório quando must_change_password é true.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@tokeflow.com",
    "current_password": "TempPass@2025Xyz",
    "new_password": "NewSecurePass@2025"
  }'

Exemplo de resposta — 200

{}

POST/api/v1/auth/forgot-password

Sempre retorna a mesma resposta 202, esteja o endereço registrado ou não, de modo que não pode ser usada para descobrir contas. O limite por e-mail é aplicado no serviço; a limitação aqui é uma salvaguarda por IP.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/forgot-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@organization.com"
  }'

Exemplo de resposta — 202

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

POST/api/v1/auth/login

Autentica os usuários internos da plataforma (super admin, platform admin, support) com e-mail e senha. Retorna um token JWT para as solicitações subsequentes à API.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/login \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "superadmin@tokeflow.com",
    "password": "SuperAdmin@123"
  }'

Exemplo de resposta — 200

{}

POST/api/v1/auth/logout

Invalida o token de atualização atual. O token de acesso expirará naturalmente.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Exemplo de resposta — 200

{}

POST/api/v1/auth/merchant/accept-invitation

Define uma senha e ativa a linha de merchant_users associada ao token de convite fornecido. Após a aceitação, o usuário pode fazer login por meio de /auth/merchant/login.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/accept-invitation \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3...e9f0",
    "password": "StrongP@ssw0rd!",
    "name": "Acme Store"
  }'

Exemplo de resposta — 200

{
  "message": "Operation completed successfully",
  "email": "jane@example.com"
}

POST/api/v1/auth/merchant/change-password

Consulta apenas merchant_users. O mesmo endereço pode ser uma identidade independente em mais de uma tabela, portanto use o endpoint que corresponda ao dashboard ao qual a senha pertence — este para merchant, organization/change-password para org, change-password para admin. Revoga os tokens de atualização; os tokens de acesso expiram em 15 minutos.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contact@organization.com",
    "current_password": "TempPass@2025Xyz",
    "new_password": "NewSecurePass@2025"
  }'

Exemplo de resposta — 200

{
  "message": "Password changed successfully",
  "email": "contact@organization.com",
  "can_login": true
}

POST/api/v1/auth/merchant/forgot-password

Sempre retorna a mesma resposta 202, esteja o endereço registrado ou não, de modo que não pode ser usada para descobrir contas.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/forgot-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@organization.com"
  }'

Exemplo de resposta — 202

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

POST/api/v1/auth/merchant/login

Autentica os usuários que foram atribuídos a merchants. Retorna o token JWT e a lista de associações de merchant para o seletor de merchant.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/login \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@merchant.com",
    "password": "Password@123"
  }'

Exemplo de resposta — 200

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@merchant.com",
    "name": "John Doe",
    "merchants": [
      {
        "membership_id": "f0f524fe-d28f-485b-bc3c-2c6acc26d12b",
        "merchant_id": "mrc_abc123",
        "merchant_name": "Store XPTO",
        "status": "active",
        "role": "owner",
        "organization_id": "org_xyz",
        "organization_name": "Acme Corp"
      }
    ],
    "last_login_at": "2026-04-09T10:00:00.000Z"
  },
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900
}

GET/api/v1/auth/merchant/memberships

Retorna todas as associações de merchant do usuário autenticado. Usado pelo frontend para exibir um seletor de contexto de merchant.

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/auth/merchant/memberships \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Exemplo de resposta — 200

{
  "memberships": [
    {
      "membership_id": "f0f524fe-d28f-485b-bc3c-2c6acc26d12b",
      "merchant_id": "mrc_abc123",
      "merchant_name": "Store XPTO",
      "status": "active",
      "role": "owner",
      "organization_id": "org_xyz",
      "organization_name": "Acme Corp"
    }
  ]
}

POST/api/v1/auth/organization/change-password

Consulta apenas organization_users. Permite que um usuário de organization com uma senha temporária a altere antes de fazer login; obrigatório quando must_change_password é true. As identidades de merchant usam merchant/change-password — o mesmo endereço pode existir de forma independente em ambas as tabelas.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contact@organization.com",
    "current_password": "TempPass@2025Xyz",
    "new_password": "NewSecurePass@2025"
  }'

Exemplo de resposta — 200

{}

POST/api/v1/auth/organization/forgot-password

Sempre retorna a mesma resposta 202, esteja o endereço registrado ou não, de modo que não pode ser usada para descobrir contas.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/forgot-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@organization.com"
  }'

Exemplo de resposta — 202

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

POST/api/v1/auth/organization/login

Autentica os usuários de organization (contatos principais e membros da organization) com e-mail e senha. Retorna o token JWT com as associações de organization.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/login \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@company.com",
    "password": "OrgPass@123"
  }'

Exemplo de resposta — 200

{}

POST/api/v1/auth/organization/logout

Invalida o token de atualização atual de um usuário de organization. O token de acesso expirará naturalmente.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Exemplo de resposta — 200

{}

GET/api/v1/auth/organization/memberships

Retorna todas as organizations às quais o usuário autenticado pertence. A resposta de login inclui a mesma lista, mas os clientes conservam apenas a organization ativa, então é assim que um seletor volta a ser preenchido após um recarregamento.

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/auth/organization/memberships \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Exemplo de resposta — 200

{
  "memberships": [
    {
      "membership_id": "f0f524fe-d28f-485b-bc3c-2c6acc26d12b",
      "organization_id": "org_abc123",
      "organization_name": "Acme Corp",
      "role": "owner"
    }
  ]
}

POST/api/v1/auth/organization/switch

Reemite esta sessão para outra organization à qual quem chama pertence, retornando um novo par de tokens. Autenticado em vez de público: a organization retornada é aquela à qual cada solicitação subsequente fica restrita, portanto quem chama deve ser um sujeito verificado, não apenas quem possui um token de atualização. 403 se quem chama não tiver associação no destino.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/switch \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_abc123"
  }'

Exemplo de resposta — 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

POST/api/v1/auth/password-reset/confirm

Consome o token, define a senha, remove qualquer bloqueio e revoga os tokens de atualização para que as sessões existentes terminem. Os tokens de acesso já emitidos permanecem válidos até expirarem (15 minutos).

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/password-reset/confirm \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "V-9nQ2h1c2VyLXRva2VuLWV4YW1wbGUtdmFsdWU",
    "new_password": "CorrectHorse1Battery"
  }'

Exemplo de resposta — 200

{
  "message": "Password reset successfully",
  "email": "user@organization.com",
  "can_login": true
}

POST/api/v1/auth/refresh

Troca um token de atualização válido por um novo par de token de acesso e token de atualização (rotação de tokens).

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/auth/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Exemplo de resposta — 200

{}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

Relacionados

• Convites
• Autenticação
• Equipe da Organization