Autenticação
Credenciais, JWT e recuperação de senha.
A API usa dois mecanismos de autenticação dependendo do contexto de uso.
API Key — integrações servidor-a-servidor
Todas as rotas de integração (/payments, /payments/pix, GET /payments, /sub-accounts) exigem dois headers:
X-Client-ID: client_a1b2c3d4e5f6g7h8
X-API-Key: sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6Cadastro de empresa (headless)
Use POST /register para criar uma empresa programaticamente — útil para plataformas que provisionam merchants automaticamente:
POST /api/v1/register
Content-Type: application/json{
"name": "Acme Corp"
}Resposta 200:
{
"message": "Company registered successfully!",
"credentials": {
"client_id": "client_a1b2c3d4e5f6g7h8",
"api_key": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"warning": "Save your api_key safely, it won't be showed again."
}
}A api_key é exibida uma única vez. Armazene imediatamente em um cofre de segredos (ex: AWS Secrets Manager, Vault). Não há endpoint de recuperação — uma nova chave exige novo cadastro.
Verificação de credenciais
curl https://dev.plugtopay.com/api/v1/ping \
-H "X-Client-ID: client_..." \
-H "X-API-Key: sk_..."Resposta 200:
{ "status": "pong" }Bearer JWT — painel administrativo
As rotas do painel (/dashboard, /user/payments, /user/company/config, /user/gateways) usam JWT emitido pelo fluxo de login de usuário.
Cadastro de usuário
POST /auth/register cria um usuário e provisiona automaticamente uma empresa associada. Retorna JWT + credenciais de API em uma única chamada:
POST /api/v1/auth/register
Content-Type: application/json{
"name": "João Silva",
"email": "joao@example.com",
"password": "secret123",
"password_confirmation": "secret123",
"company_name": "Minha Empresa"
}Resposta 201:
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_at": "2026-05-27T12:00:00+00:00",
"user": {
"id": 1,
"name": "João Silva",
"email": "joao@example.com",
"company_id": 1
},
"company": {
"name": "Minha Empresa",
"client_id": "client_a1b2c3d4e5f6g7h8",
"api_key": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"warning": "Save your api_key safely, it won't be shown again."
}
}A api_key retornada em /auth/register também é exibida uma única vez. Armazene antes de prosseguir.
Login
POST /api/v1/auth/login
Content-Type: application/json{
"email": "joao@example.com",
"password": "secret123"
}Resposta 200:
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_at": "2026-05-27T12:00:00+00:00",
"user": {
"id": 1,
"name": "João Silva",
"email": "joao@example.com",
"company_id": 1
}
}Use o token retornado nos headers das rotas de painel:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...Recuperação de senha
1. Solicitar reset:
POST /api/v1/auth/forgot-password
Content-Type: application/json{ "email": "joao@example.com" }Resposta 200:
{
"message": "Reset instructions sent.",
"reset_token": "abc123...",
"expires_in": "60 minutes"
}2. Definir nova senha:
POST /api/v1/auth/reset-password
Content-Type: application/json{
"token": "abc123...",
"password": "newpassword123",
"password_confirmation": "newpassword123"
}