Autenticação

A API Maestron usa autenticação baseada em Bearer token. Após autenticar, todas as requisições aos endpoints protegidos enviam o token no header Authorization. A empresa (tenant) ativa é resolvida automaticamente a partir do token — não há nenhum header de empresa.

Bearer token

Todo endpoint protegido exige o header HTTP Authorization no formato:

Authorization: Bearer SEU_TOKEN

Os endpoints de autenticação públicos (login, registro, refresh, social, 2FA e recuperação de senha) não exigem Authorization. Todos os demais endpoints da API exigem.

Expiração e remember_me

• O token de acesso possui um tempo de vida (TTL) limitado e expira após o período padrão.
• Quando a autenticação é feita com remember_me: true, o TTL do token é estendido para um período mais longo.
• Um token expirado retorna 401. Use o endpoint de refresh para obter um novo token sem reautenticar com credenciais.
• O campo expires_in da resposta indica, em segundos, o tempo restante até a expiração do token retornado.

Resposta de autenticação

As respostas de login, registro, refresh, callback social e verificação de 2FA retornam o mesmo objeto: token, token_type (Bearer), expires_in (segundos) e user.

Resolução automática de empresa

O token carrega o contexto da empresa ativa do usuário. A API resolve o tenant a partir do próprio token — não existe e não deve ser enviado nenhum header de empresa.

Para operar em outra empresa à qual o usuário pertence, emita um novo token com o contexto daquela empresa via POST /auth/context. O token resultante já resolve a empresa sozinho em todas as requisições subsequentes.

Sem header de empresa

Nunca envie um header de identificação de empresa. O contexto do tenant é sempre derivado do token. Para trocar de empresa, troque o token.

---

Login

Autentica com e-mail e senha e retorna um Bearer token. Quando o usuário possui 2FA habilitado, a resposta indica que a verificação do segundo fator é necessária antes da emissão do token de acesso.

POST /auth/login Copiar para LLM

Login

Autentica o usuário e emite um Bearer token.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	E-mail do usuário.
password	string	Sim	Senha do usuário.
remember_me	boolean	—	Quando true, estende o TTL do token emitido.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@empresa.com.br",
    "password": "senha-secreta",
    "remember_me": true
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/login', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'email' => 'usuario@empresa.com.br',
        'password' => 'senha-secreta',
        'remember_me' => true,
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "email": "usuario@empresa.com.br",
    "password": "senha-secreta",
    "remember_me": True,
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/login",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "usuario@empresa.com.br",
    "password": "senha-secreta",
    "remember_me": true
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"email\":\"usuario@empresa.com.br\",\"password\":\"senha-secreta\",\"remember_me\":true}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/login", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/login HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "email": "usuario@empresa.com.br",
  "password": "senha-secreta",
  "remember_me": true
}

Respostas

200 · Sucesso200 · 2FA necessário401 · Credenciais inválidas422 · Validação429 · Limite excedido

{
  "message": "Autenticado com sucesso.",
  "data": {
    "token": "mtk_01J9Z3K8ABCDEF...",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Silva",
      "email": "usuario@empresa.com.br",
      "company_id": "comp_01J9Z3K8"
    }
  }
}

{
  "message": "Verificação de dois fatores necessária.",
  "data": {
    "two_factor_required": true,
    "two_factor_token": "2fa_01J9Z3K8..."
  }
}

{
  "message": "Credenciais inválidas."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": [
      "O campo e-mail é obrigatório."
    ],
    "password": [
      "O campo senha é obrigatório."
    ]
  }
}

{
  "message": "Muitas tentativas de login. Tente novamente mais tarde."
}

---

Refresh token

Emite um novo Bearer token a partir de um token válido (ainda não expirado), prorrogando a sessão sem reautenticar com credenciais.

POST /auth/refresh Copiar para LLM

Renovar token

Renova o Bearer token e retorna um novo token de acesso.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/refresh \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/refresh', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/refresh",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/refresh", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/refresh", null);
var data = await response.Content.ReadAsStringAsync();

POST /auth/refresh HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Sucesso401 · Não autenticado

{
  "message": "Token renovado.",
  "data": {
    "token": "mtk_01J9Z3K8NEWTOKEN...",
    "token_type": "Bearer",
    "expires_in": 2592000
  }
}

{
  "message": "Token inválido ou expirado."
}

---

Logout

Invalida o token atual e encerra a sessão. Após o logout, o token não pode mais ser usado.

POST /auth/logout Copiar para LLM

Logout

Invalida o token atual e encerra a sessão.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/logout \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/logout', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/logout",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/logout", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/logout", null);
var data = await response.Content.ReadAsStringAsync();

POST /auth/logout HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Sucesso401 · Não autenticado

{
  "message": "Sessão encerrada."
}

{
  "message": "Token inválido ou expirado."
}

---

Registro

Cria um novo usuário e sua empresa inicial, retornando um Bearer token já com o contexto da empresa criada.

POST /auth/register Copiar para LLM

Registrar

Cria um novo usuário e empresa e emite um Bearer token.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do usuário.
email	string	Sim	E-mail do usuário. Deve ser único.
password	string	Sim	Senha do usuário.
password_confirmation	string	Sim	Confirmação da senha.
company_name	string	Sim	Nome da empresa a ser criada.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "usuario@empresa.com.br",
    "password": "senha-secreta",
    "password_confirmation": "senha-secreta",
    "company_name": "Empresa Exemplo Ltda"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/register', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'name' => 'Maria Silva',
        'email' => 'usuario@empresa.com.br',
        'password' => 'senha-secreta',
        'password_confirmation' => 'senha-secreta',
        'company_name' => 'Empresa Exemplo Ltda',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "name": "Maria Silva",
    "email": "usuario@empresa.com.br",
    "password": "senha-secreta",
    "password_confirmation": "senha-secreta",
    "company_name": "Empresa Exemplo Ltda",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/register",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/register", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Maria Silva",
    "email": "usuario@empresa.com.br",
    "password": "senha-secreta",
    "password_confirmation": "senha-secreta",
    "company_name": "Empresa Exemplo Ltda"
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"name\":\"Maria Silva\",\"email\":\"usuario@empresa.com.br\",\"password\":\"senha-secreta\",\"password_confirmation\":\"senha-secreta\",\"company_name\":\"Empresa Exemplo Ltda\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/register", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/register HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "name": "Maria Silva",
  "email": "usuario@empresa.com.br",
  "password": "senha-secreta",
  "password_confirmation": "senha-secreta",
  "company_name": "Empresa Exemplo Ltda"
}

Respostas

201 · Criado422 · Validação429 · Limite excedido

{
  "message": "Conta criada.",
  "data": {
    "token": "mtk_01J9Z3K8ABCDEF...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Silva",
      "email": "usuario@empresa.com.br",
      "company_id": "comp_01J9Z3K8"
    }
  }
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": [
      "Este e-mail já está em uso."
    ],
    "password": [
      "A senha deve ter no mínimo 8 caracteres."
    ]
  }
}

{
  "message": "Muitas tentativas. Tente novamente mais tarde."
}

---

Usuário autenticado

Retorna os dados do usuário associado ao token, incluindo a empresa ativa resolvida a partir dele.

GET /auth/me Copiar para LLM

Usuário autenticado

Retorna os dados do usuário autenticado e a empresa ativa.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/v1/auth/me \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/auth/me', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/v1/auth/me",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/me", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/v1/auth/me");
var data = await response.Content.ReadAsStringAsync();

GET /auth/me HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Sucesso401 · Não autenticado

{
  "message": "Registro retornado.",
  "data": {
    "id": "user_01J9Z3K8",
    "name": "Maria Silva",
    "email": "usuario@empresa.com.br",
    "company_id": "comp_01J9Z3K8",
    "two_factor_enabled": true,
    "created_at": "2026-01-15T10:00:00Z"
  }
}

{
  "message": "Token inválido ou expirado."
}

---

OAuth social

O login social segue três etapas: obter a URL de autorização do provedor, processar o callback do provedor e trocar o código por um Bearer token. Provedores suportados são identificados pelo parâmetro de rota provider (por exemplo google).

Obter URL de redirecionamento

Retorna a URL de autorização do provedor para a qual o fluxo OAuth deve ser direcionado.

GET /auth/social/{provider}/redirect Copiar para LLM

Redirect social

Retorna a URL de autorização do provedor OAuth.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
provider	string	Sim	Identificador do provedor (ex.: google).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/v1/auth/social/{provider}/redirect

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/auth/social/{provider}/redirect', [
    'headers' => ['Accept' => 'application/json'],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
response = requests.get(
    "https://api.maestron.com.br/v1/auth/social/{provider}/redirect",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/social/{provider}/redirect", {
  method: "GET",
  headers: {
  },
});
const data = await response.json();

using var client = new HttpClient();
var response = await client.GetAsync("https://api.maestron.com.br/v1/auth/social/{provider}/redirect");
var data = await response.Content.ReadAsStringAsync();

GET /auth/social/{provider}/redirect HTTP/1.1
Host: api.maestron.com.br

Respostas

200 · Sucesso404 · Provedor inexistente

{
  "message": "Registro retornado.",
  "data": {
    "redirect_url": "https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...&state=..."
  }
}

{
  "message": "Provedor não suportado."
}

Callback do provedor

Endpoint para o qual o provedor OAuth redireciona após a autorização. Processa o code e o state e retorna um código de troca de uso único.

GET /auth/social/{provider}/callback Copiar para LLM

Callback social

Processa o retorno do provedor OAuth e emite um código de troca.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
provider	string	Sim	Identificador do provedor (ex.: google).

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
code	string	Sim	Código de autorização retornado pelo provedor.
state	string	Sim	Valor de estado para proteção contra CSRF.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/v1/auth/social/{provider}/callback

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/auth/social/{provider}/callback', [
    'headers' => ['Accept' => 'application/json'],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
response = requests.get(
    "https://api.maestron.com.br/v1/auth/social/{provider}/callback",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/social/{provider}/callback", {
  method: "GET",
  headers: {
  },
});
const data = await response.json();

using var client = new HttpClient();
var response = await client.GetAsync("https://api.maestron.com.br/v1/auth/social/{provider}/callback");
var data = await response.Content.ReadAsStringAsync();

GET /auth/social/{provider}/callback HTTP/1.1
Host: api.maestron.com.br

Respostas

200 · Sucesso401 · Falha na autorização422 · Validação

{
  "message": "Registro retornado.",
  "data": {
    "exchange_code": "xch_01J9Z3K8..."
  }
}

{
  "message": "Não foi possível autenticar com o provedor."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "code": [
      "O campo code é obrigatório."
    ]
  }
}

Trocar código por token

Troca o código de uso único, obtido no callback, por um Bearer token.

POST /auth/social/exchange Copiar para LLM

Trocar código social

Troca o código de uso único por um Bearer token.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
exchange_code	string	Sim	Código de troca retornado pelo callback.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/social/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_code": "xch_01J9Z3K8..."
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/social/exchange', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'exchange_code' => 'xch_01J9Z3K8...',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "exchange_code": "xch_01J9Z3K8...",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/social/exchange",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/social/exchange", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "exchange_code": "xch_01J9Z3K8..."
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"exchange_code\":\"xch_01J9Z3K8...\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/social/exchange", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/social/exchange HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "exchange_code": "xch_01J9Z3K8..."
}

Respostas

200 · Sucesso401 · Código inválido422 · Validação

{
  "message": "Autenticado com sucesso.",
  "data": {
    "token": "mtk_01J9Z3K8ABCDEF...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Silva",
      "email": "usuario@empresa.com.br",
      "company_id": "comp_01J9Z3K8"
    }
  }
}

{
  "message": "Código de troca inválido ou expirado."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "exchange_code": [
      "O campo exchange_code é obrigatório."
    ]
  }
}

---

Autenticação em dois fatores (2FA)

Quando o login retorna two_factor_required, use o two_factor_token recebido para verificar o código do segundo fator. Após a verificação bem-sucedida, o Bearer token de acesso é emitido.

Verificar código

Valida o código de 2FA e emite o Bearer token de acesso.

POST /auth/two-factor/verify Copiar para LLM

Verificar 2FA

Valida o código de dois fatores e emite o Bearer token.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
two_factor_token	string	Sim	Token de 2FA retornado pelo login.
code	string	Sim	Código de verificação de seis dígitos.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/two-factor/verify \
  -H "Content-Type: application/json" \
  -d '{
    "two_factor_token": "2fa_01J9Z3K8...",
    "code": "123456"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/two-factor/verify', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'two_factor_token' => '2fa_01J9Z3K8...',
        'code' => '123456',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "two_factor_token": "2fa_01J9Z3K8...",
    "code": "123456",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/two-factor/verify",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/two-factor/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "two_factor_token": "2fa_01J9Z3K8...",
    "code": "123456"
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"two_factor_token\":\"2fa_01J9Z3K8...\",\"code\":\"123456\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/two-factor/verify", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/two-factor/verify HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "two_factor_token": "2fa_01J9Z3K8...",
  "code": "123456"
}

Respostas

200 · Sucesso401 · Código inválido422 · Validação429 · Limite excedido

{
  "message": "Autenticado com sucesso.",
  "data": {
    "token": "mtk_01J9Z3K8ABCDEF...",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Silva",
      "email": "usuario@empresa.com.br",
      "company_id": "comp_01J9Z3K8"
    }
  }
}

{
  "message": "Código de verificação inválido ou expirado."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "code": [
      "O campo code é obrigatório."
    ]
  }
}

{
  "message": "Muitas tentativas. Tente novamente mais tarde."
}

Reenviar código

Reenvia o código de 2FA para o canal configurado, usando o token de 2FA obtido no login.

POST /auth/two-factor/resend Copiar para LLM

Reenviar 2FA

Reenvia o código de dois fatores.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
two_factor_token	string	Sim	Token de 2FA retornado pelo login.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/two-factor/resend \
  -H "Content-Type: application/json" \
  -d '{
    "two_factor_token": "2fa_01J9Z3K8..."
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/two-factor/resend', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'two_factor_token' => '2fa_01J9Z3K8...',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "two_factor_token": "2fa_01J9Z3K8...",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/two-factor/resend",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/two-factor/resend", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "two_factor_token": "2fa_01J9Z3K8..."
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"two_factor_token\":\"2fa_01J9Z3K8...\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/two-factor/resend", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/two-factor/resend HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "two_factor_token": "2fa_01J9Z3K8..."
}

Respostas

200 · Sucesso401 · Token inválido422 · Validação429 · Limite excedido

{
  "message": "Código reenviado."
}

{
  "message": "Token de dois fatores inválido ou expirado."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "two_factor_token": [
      "O campo two_factor_token é obrigatório."
    ]
  }
}

{
  "message": "Muitas tentativas. Tente novamente mais tarde."
}

---

Recuperação de senha

O fluxo de recuperação tem duas etapas: solicitar o envio do link de redefinição e redefinir a senha com o token recebido.

Solicitar redefinição

Envia um e-mail com o token de redefinição para o endereço informado.

POST /auth/forgot-password Copiar para LLM

Esqueci a senha

Solicita o envio do link de redefinição de senha.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	E-mail da conta.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@empresa.com.br"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/forgot-password', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'email' => 'usuario@empresa.com.br',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "email": "usuario@empresa.com.br",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/forgot-password",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/forgot-password", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "usuario@empresa.com.br"
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"email\":\"usuario@empresa.com.br\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/forgot-password", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/forgot-password HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "email": "usuario@empresa.com.br"
}

Respostas

200 · Sucesso422 · Validação429 · Limite excedido

{
  "message": "Link de redefinição enviado."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": [
      "O campo e-mail é obrigatório."
    ]
  }
}

{
  "message": "Muitas tentativas. Tente novamente mais tarde."
}

Redefinir senha

Define uma nova senha usando o token recebido por e-mail.

POST /auth/reset-password Copiar para LLM

Redefinir senha

Define uma nova senha a partir do token de redefinição.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
token	string	Sim	Token de redefinição recebido por e-mail.
email	string	Sim	E-mail da conta.
password	string	Sim	Nova senha.
password_confirmation	string	Sim	Confirmação da nova senha.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "rst_01J9Z3K8...",
    "email": "usuario@empresa.com.br",
    "password": "nova-senha-secreta",
    "password_confirmation": "nova-senha-secreta"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/reset-password', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'token' => 'rst_01J9Z3K8...',
        'email' => 'usuario@empresa.com.br',
        'password' => 'nova-senha-secreta',
        'password_confirmation' => 'nova-senha-secreta',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "token": "rst_01J9Z3K8...",
    "email": "usuario@empresa.com.br",
    "password": "nova-senha-secreta",
    "password_confirmation": "nova-senha-secreta",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/reset-password",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/reset-password", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "token": "rst_01J9Z3K8...",
    "email": "usuario@empresa.com.br",
    "password": "nova-senha-secreta",
    "password_confirmation": "nova-senha-secreta"
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"token\":\"rst_01J9Z3K8...\",\"email\":\"usuario@empresa.com.br\",\"password\":\"nova-senha-secreta\",\"password_confirmation\":\"nova-senha-secreta\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/reset-password", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/reset-password HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "token": "rst_01J9Z3K8...",
  "email": "usuario@empresa.com.br",
  "password": "nova-senha-secreta",
  "password_confirmation": "nova-senha-secreta"
}

Respostas

200 · Sucesso401 · Token inválido422 · Validação

{
  "message": "Senha redefinida."
}

{
  "message": "Token de redefinição inválido ou expirado."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "password": [
      "A confirmação da senha não confere."
    ]
  }
}

---

Trocar empresa ativa

Emite um novo Bearer token com o contexto de outra empresa à qual o usuário pertence. O token resultante resolve essa empresa automaticamente em todas as requisições.

POST /auth/context Copiar para LLM

Trocar empresa ativa

Emite um novo token com o contexto da empresa informada.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
company_id	string	Sim	Identificador da empresa de destino (prefixo comp_).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/context \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "comp_01J9Z3K8"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/context', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'company_id' => 'comp_01J9Z3K8',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "company_id": "comp_01J9Z3K8",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/context",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/context", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": "comp_01J9Z3K8"
  }),
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"company_id\":\"comp_01J9Z3K8\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/context", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/context HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "company_id": "comp_01J9Z3K8"
}

Respostas

200 · Sucesso401 · Não autenticado403 · Sem acesso404 · Empresa inexistente422 · Validação

{
  "message": "Empresa ativa alterada.",
  "data": {
    "token": "mtk_01J9Z3K8NEWCTX...",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "company_id": "comp_01J9Z3K8"
  }
}

{
  "message": "Token inválido ou expirado."
}

{
  "message": "O usuário não pertence à empresa informada."
}

{
  "message": "Empresa não encontrada."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "company_id": [
      "O campo company_id é obrigatório."
    ]
  }
}

---

Para os códigos de status e o formato das respostas de erro, consulte Erros. Para os limites de requisição, consulte Rate limiting.