Fluxo de autenticação

Este guia detalha o fluxo completo de autenticação da API Maestron: como obter um token, mantê-lo válido com refresh, autenticar via provedores OAuth, lidar com 2FA, redefinir senhas e trocar o contexto de empresa.

A autenticação é baseada em token Bearer. Toda requisição autenticada envia o token no header Authorization. A empresa (tenant) é resolvida automaticamente a partir do token — não existe nem deve ser enviado nenhum header de empresa. Consulte Autenticação para o resumo das regras e Erros para o detalhamento dos códigos de status.

Visão geral do fluxo

1. Obter token. Autentique com POST /auth/login (ou via OAuth social, ou após validar 2FA). A resposta traz token, token_type e expires_in.

2. Usar token. Envie Authorization: Bearer SEU_TOKEN em todas as requisições autenticadas. A empresa ativa é deduzida do próprio token.

3. Renovar token. Antes da expiração, chame POST /auth/refresh com o token atual para obter um novo token sem reenviar credenciais.

4. Trocar de empresa (opcional). Se o usuário pertence a mais de uma empresa, POST /auth/context emite um novo token vinculado à empresa escolhida.

5. Encerrar. POST /auth/logout invalida o token atual.

Ciclo de vida do token

O token retornado por login, refresh, social e validação de 2FA segue o mesmo formato:

Campo	Tipo	Descrição
token	string	Token Bearer a ser enviado no header Authorization.
token_type	string	Sempre Bearer.
expires_in	integer	Tempo de vida do token em segundos.
expires_at	string (ISO-8601)	Momento exato da expiração.

Regras do ciclo de vida:

• O expires_in padrão é de 1 hora (3600). Com remember_me: true no login, o token tem TTL estendido.
• Um token expirado retorna 401 em qualquer endpoint autenticado.
• refresh deve ser chamado antes da expiração: ele recebe o token corrente (ainda válido) e devolve um novo token, estendendo a sessão sem credenciais.
• Após logout, o token é invalidado imediatamente e não pode ser renovado.
• A troca de contexto de empresa (POST /auth/context) gera um novo token; o token anterior continua válido até expirar ou até logout, mas resolve a empresa antiga.

Nota

A empresa ativa está embutida no token. Para operar em outra empresa do mesmo usuário, obtenha um token novo via POST /auth/context — nenhum header adicional substitui isso.

Login com e-mail e senha

Autentica o usuário com credenciais e devolve um token Bearer. Use remember_me para um token de vida mais longa.

POST /auth/login Copiar para LLM

Login

Autentica com e-mail e senha e retorna um token Bearer.

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, emite um token com TTL estendido.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@suaempresa.com",
    "password": "sua_senha",
    "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' => 'dev@suaempresa.com',
        'password' => 'sua_senha',
        'remember_me' => true,
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "email": "dev@suaempresa.com",
    "password": "sua_senha",
    "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": "dev@suaempresa.com",
    "password": "sua_senha",
    "remember_me": true
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"email\":\"dev@suaempresa.com\",\"password\":\"sua_senha\",\"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": "dev@suaempresa.com",
  "password": "sua_senha",
  "remember_me": true
}

Respostas

200 · Sessão iniciada.401 · Credenciais inválidas.403 · 2FA obrigatório.422 · Validação.429 · Muitas tentativas.

{
  "message": "Sessão iniciada.",
  "data": {
    "token": "mtk_01J9Z3K8XQ2R7VN4P0WBHF6CDE",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-06-20T15:30:00Z",
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Oliveira",
      "email": "dev@suaempresa.com"
    }
  }
}

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

{
  "message": "Verificação em duas etapas obrigatória.",
  "data": {
    "two_factor_required": true,
    "challenge_id": "chl_01J9Z3K8"
  }
}

{
  "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. Tente novamente mais tarde."
}

Quando a conta tem 2FA habilitado, o login retorna 403 com two_factor_required: true e um challenge_id. Nesse caso, conclua o fluxo em Verificação em duas etapas (2FA) em vez de receber o token diretamente.

Refresh automático do token

refresh recebe o token atual (ainda válido) no header Authorization e devolve um token novo. A estratégia recomendada é renovar de forma reativa: ao receber um 401 em uma requisição que falhou por token expirado, chamar refresh uma única vez, atualizar o token em uso e repetir a requisição original.

A lógica essencial, independente de linguagem, é:

1. Uma requisição autenticada retorna 401.

2. Dispara-se uma chamada a POST /auth/refresh com o token corrente. Requisições concorrentes que também receberam 401 aguardam o resultado dessa única renovação.

3. Em sucesso, o novo token substitui o anterior e as requisições pendentes são repetidas com o token atualizado.

4. Em falha (401 no próprio refresh), a sessão é considerada encerrada e o usuário deve autenticar novamente.

POST /auth/refresh Copiar para LLM

Renovar token

Troca o token atual por um novo, estendendo a sessão sem reenviar credenciais.

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 · Token renovado.401 · Token inválido ou expirado.

{
  "message": "Token renovado.",
  "data": {
    "token": "mtk_01J9Z4A2NEWTOKEN7QPLM3RXYZ",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-06-20T16:30:00Z"
  }
}

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

Dica

Ao tratar 401 de forma centralizada, garanta que múltiplas requisições simultâneas com token expirado aguardem uma única renovação, em vez de cada uma disparar seu próprio refresh.

OAuth social

O login social segue o padrão redirect → callback → exchange. O cliente leva o usuário ao provedor; o provedor redireciona de volta com um code; o code é trocado por um token Bearer da API Maestron.

1. Redirect. Obtenha a URL de autorização do provedor em GET /auth/social/{provider}/redirect e direcione o usuário para ela.

2. Callback. O provedor redireciona o usuário de volta à redirect_uri registrada, anexando code e state.

3. Exchange. Envie code e state para POST /auth/social/{provider}/callback. A resposta é um token Bearer no mesmo formato do login.

Provedores suportados: google, github, microsoft. O state retornado no passo 1 deve ser reenviado no passo 3 para proteção contra CSRF.

Passo 1 — obter a URL de redirecionamento

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

Iniciar OAuth social

Retorna a URL de autorização do provedor e o state a ser validado no callback.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
provider	string	Sim	Provedor OAuth: google, github ou microsoft.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
redirect_uri	string	—	URI de retorno registrada para a aplicação.

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 · URL gerada.404 · Provedor não suportado.422 · Validação.

{
  "message": "URL de autorização gerada.",
  "data": {
    "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=st_01J9Z3K8",
    "state": "st_01J9Z3K8"
  }
}

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

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "redirect_uri": [
      "A URI de retorno é inválida."
    ]
  }
}

Passo 2 — trocar o code por um token

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

Concluir OAuth social

Troca o code recebido do provedor por um token Bearer da API.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
provider	string	Sim	Provedor OAuth: google, github ou microsoft.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
code	string	Sim	Código de autorização retornado pelo provedor.
state	string	Sim	State retornado no passo de redirect, para validação CSRF.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/social/{provider}/callback \
  -H "Content-Type: application/json" \
  -d '{
    "code": "4/0AbCD_eFgHiJkLmNoPqRsTuVwXyZ",
    "state": "st_01J9Z3K8"
  }'

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

import requests
headers = {}
payload = {
    "code": "4/0AbCD_eFgHiJkLmNoPqRsTuVwXyZ",
    "state": "st_01J9Z3K8",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/social/{provider}/callback",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/social/{provider}/callback", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "code": "4/0AbCD_eFgHiJkLmNoPqRsTuVwXyZ",
    "state": "st_01J9Z3K8"
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"code\":\"4/0AbCD_eFgHiJkLmNoPqRsTuVwXyZ\",\"state\":\"st_01J9Z3K8\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/social/{provider}/callback", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/social/{provider}/callback HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "code": "4/0AbCD_eFgHiJkLmNoPqRsTuVwXyZ",
  "state": "st_01J9Z3K8"
}

Respostas

200 · Sessão iniciada.401 · Code inválido ou expirado.404 · Provedor não suportado.422 · Validação.

{
  "message": "Sessão iniciada.",
  "data": {
    "token": "mtk_01J9Z5SOCIAL8TOKEN4QPLM3RXY",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-06-20T15:30:00Z",
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Oliveira",
      "email": "dev@suaempresa.com"
    }
  }
}

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

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

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "state": [
      "O state informado não corresponde ao redirect."
    ]
  }
}

Verificação em duas etapas (2FA)

Quando o login detecta 2FA habilitado, ele retorna 403 com two_factor_required: true e um challenge_id, em vez do token. O cliente coleta o código (TOTP do app autenticador ou código de recuperação) e o submete a POST /auth/two-factor/challenge. Em sucesso, o token Bearer é emitido.

1. POST /auth/login retorna 403 com challenge_id.

2. O usuário informa o código de 6 dígitos do app autenticador (ou um código de recuperação).

3. POST /auth/two-factor/challenge valida o código e retorna o token.

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

Validar 2FA

Valida o código de verificação em duas etapas e retorna o token Bearer.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
challenge_id	string	Sim	Identificador do desafio retornado pelo login.
code	string	—	Código TOTP de 6 dígitos do app autenticador.
recovery_code	string	—	Código de recuperação, alternativo ao code.

cURLPHPPythonNode.jsC#HTTP / Postman

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

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

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

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

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

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

{
  "challenge_id": "chl_01J9Z3K8",
  "code": "123456"
}

Respostas

200 · Sessão iniciada.401 · Código inválido.404 · Desafio inexistente.422 · Validação.429 · Muitas tentativas.

{
  "message": "Sessão iniciada.",
  "data": {
    "token": "mtk_01J9Z6TWOFA4TOKEN7QPLM3RXY",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-06-20T15:30:00Z"
  }
}

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

{
  "message": "Desafio de verificação não encontrado."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "code": [
      "Informe o código ou um código de recuperação."
    ]
  }
}

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

Redefinição de senha

O reset de senha tem duas etapas: solicitar o e-mail com o link/token de redefinição e, em seguida, enviar a nova senha junto do token recebido. Ambos os endpoints são públicos.

Solicitar redefinição

POST /auth/forgot-password Copiar para LLM

Solicitar redefinição de senha

Envia ao e-mail informado um token de redefinição de senha.

Corpo (body)

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

cURLPHPPythonNode.jsC#HTTP / Postman

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

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

import requests
headers = {}
payload = {
    "email": "dev@suaempresa.com",
}
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": "dev@suaempresa.com"
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"email\":\"dev@suaempresa.com\"}",
    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": "dev@suaempresa.com"
}

Respostas

200 · Solicitação registrada.422 · Validação.429 · Muitas tentativas.

{
  "message": "Se o e-mail existir, enviaremos as instruções de redefinição."
}

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

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

Nota

A resposta é a mesma exista ou não a conta, para não revelar quais e-mails estão cadastrados.

Confirmar nova senha

POST /auth/reset-password Copiar para LLM

Confirmar nova senha

Define uma nova senha usando o token de redefinição recebido por e-mail.

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": "rpt_01J9Z3K8RESET0TOKEN4QPLM3R",
    "email": "dev@suaempresa.com",
    "password": "nova_senha_segura",
    "password_confirmation": "nova_senha_segura"
  }'

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

import requests
headers = {}
payload = {
    "token": "rpt_01J9Z3K8RESET0TOKEN4QPLM3R",
    "email": "dev@suaempresa.com",
    "password": "nova_senha_segura",
    "password_confirmation": "nova_senha_segura",
}
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": "rpt_01J9Z3K8RESET0TOKEN4QPLM3R",
    "email": "dev@suaempresa.com",
    "password": "nova_senha_segura",
    "password_confirmation": "nova_senha_segura"
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"token\":\"rpt_01J9Z3K8RESET0TOKEN4QPLM3R\",\"email\":\"dev@suaempresa.com\",\"password\":\"nova_senha_segura\",\"password_confirmation\":\"nova_senha_segura\"}",
    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": "rpt_01J9Z3K8RESET0TOKEN4QPLM3R",
  "email": "dev@suaempresa.com",
  "password": "nova_senha_segura",
  "password_confirmation": "nova_senha_segura"
}

Respostas

200 · Senha redefinida.401 · Token inválido ou expirado.422 · 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 corresponde."
    ]
  }
}

Trocar contexto de empresa

Se o usuário pertence a mais de uma empresa, POST /auth/context emite um novo token vinculado à empresa escolhida. O token resultante resolve a empresa sozinho — nenhum header de empresa é necessário em requisições subsequentes.

POST /auth/context Copiar para LLM

Trocar contexto de empresa

Emite um novo token vinculado à empresa informada, dentre as que o usuário pertence.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
company_id	string	Sim	Identificador da empresa para a qual emitir o novo token.

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 · Contexto alterado.401 · Não autenticado.403 · Sem acesso à empresa.404 · Empresa não encontrada.422 · Validação.

{
  "message": "Contexto alterado.",
  "data": {
    "token": "mtk_01J9Z7CTX4TOKEN7QPLM3RXYZ0",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-06-20T15:30:00Z",
    "company": {
      "id": "comp_01J9Z3K8",
      "name": "Maestron Matriz"
    }
  }
}

{
  "message": "Não autenticado."
}

{
  "message": "Você não tem acesso a esta empresa."
}

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

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

Encerrar sessão

logout invalida o token corrente. Após o sucesso, o token não pode mais ser usado nem renovado.

POST /auth/logout Copiar para LLM

Logout

Invalida o token Bearer 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 · Sessão encerrada.401 · Não autenticado.

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

{
  "message": "Não autenticado."
}

Resumo dos endpoints

Endpoint	Autenticado	Função
POST /auth/login	Não	Login com e-mail e senha.
POST /auth/refresh	Sim	Renova o token corrente.
GET /auth/social/{provider}/redirect	Não	Inicia o OAuth social.
POST /auth/social/{provider}/callback	Não	Troca o code por token.
POST /auth/two-factor/challenge	Não	Valida o 2FA e emite o token.
POST /auth/forgot-password	Não	Solicita redefinição de senha.
POST /auth/reset-password	Não	Confirma a nova senha.
POST /auth/context	Sim	Troca o contexto de empresa.
POST /auth/logout	Sim	Encerra a sessão.