Autenticação

A API pública do Vmix Pay usa OAuth2 client_credentials. Você troca suas credenciais (client_id + client_secret) por um access_token Bearer de curta duração e usa esse token nas chamadas de negócio — o client_secret nunca acompanha as requisições.

Credencial do painel ≠ token de acesso

O par client_id/client_secret que você cria no painel não é usado diretamente como Bearer. Ele serve apenas para obter o access_token no endpoint POST /v1/oauth/token. O Bearer das chamadas de negócio é o access_token retornado por esse endpoint.

Passo a passo

1. Crie a credencial no painel.

   Acesse /painel/tokens no painel do Vmix Pay e gere uma credencial de API. Você recebe um client_id e um client_secret.

   O client_secret é exibido uma única vez

   O client_secret é mostrado apenas no momento da criação (render-once). Copie e guarde-o num cofre de segredos. Se perdê-lo, rotacione a credencial no painel para gerar um novo. Cada credencial tem scopes próprios.

2. Obtenha o access_token.

   Faça POST /v1/oauth/token com as credenciais no header Authorization: Basic base64(client_id:client_secret) e o corpo grant_type=client_credentials. O corpo pode ser application/x-www-form-urlencoded ou application/json.

   Use Basic auth — não mande a credencial no corpo

   As credenciais vão no header Authorization: Basic. Não envie client_id ou client_secret no corpo da requisição.

   A resposta 200 traz o token e seus metadados:

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "token_type": "Bearer",
     "expires_in": 900,
     "scope": "charges:create charges:read"
   }

3. Chame a API com o Bearer.

   Use o access_token no header Authorization: Bearer <access_token> em todas as chamadas de negócio (e o header Idempotency-Key nas operações financeiras — veja Erros & Idempotência).

Obtendo o token

curl

curl -X POST https://api.vmixpay.com.br/v1/oauth/token \
  -u "SEU_CLIENT_ID:SEU_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

A flag -u do curl monta o header Authorization: Basic automaticamente.

Node.js

const creds = Buffer.from(
  `${process.env.VMIX_CLIENT_ID}:${process.env.VMIX_CLIENT_SECRET}`,
).toString("base64");

const res = await fetch("https://api.vmixpay.com.br/v1/oauth/token", {
  method: "POST",
  headers: {
    Authorization: `Basic ${creds}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ grant_type: "client_credentials" }),
});

const { access_token, expires_in } = await res.json();

PHP

<?php
$creds = base64_encode(getenv('VMIX_CLIENT_ID') . ':' . getenv('VMIX_CLIENT_SECRET'));

$ch = curl_init('https://api.vmixpay.com.br/v1/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Basic ' . $creds,
        'Content-Type: application/x-www-form-urlencoded',
    ],
    CURLOPT_POSTFIELDS => 'grant_type=client_credentials',
]);

$token = json_decode(curl_exec($ch), true)['access_token'];

Python

import requests

res = requests.post(
    "https://api.vmixpay.com.br/v1/oauth/token",
    auth=("SEU_CLIENT_ID", "SEU_CLIENT_SECRET"),  # Basic auth
    data={"grant_type": "client_credentials"},
)
access_token = res.json()["access_token"]

Usando o token

curl https://api.vmixpay.com.br/v1/charges/<charge_id> \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Validade e renovação

O access_token é um JWT de curta duração — o campo expires_in é o TTL em segundos (tipicamente ~900s / 15 minutos). Quando ele expirar, re-emita um novo chamando POST /v1/oauth/token de novo. Uma estratégia comum é guardar o token em cache e renová-lo um pouco antes de expires_in vencer.

A revogação é quase instantânea

Se você revogar uma credencial no painel, os tokens emitidos por ela deixam de ser aceitos em segundos (deny-list). Rotacione a credencial se suspeitar de vazamento do client_secret.

Erros de autenticação

O POST /v1/oauth/token segue o formato de erro da RFC 6749 §5.2 — diferente do envelope de erro padrão do resto da API:

HTTP	Corpo	Quando
400	{ "error": "unsupported_grant_type" }	grant_type ausente ou diferente de client_credentials.
401	{ "error": "invalid_client" }	Credenciais ausentes, malformadas ou inválidas.
429	Envelope de erro padrão	Limite de tentativas excedido (proteção contra brute-force; 5/min por IP).

invalid_client é genérico de propósito

O 401 invalid_client nunca revela se foi o client_id que não existe ou o client_secret que estava errado — é uma defesa anti-enumeração.