Guia de Autenticação

Este guia explica passo a passo como obter um token de acesso para utilizar a API PIX da CorpX.

Visão Geral

A API CorpX utiliza OAuth 2.0 com o fluxo Client Credentials para autenticação. Você precisará das suas credenciais (client_id e client_secret) para obter um token de acesso válido.

Pré-requisitos

Antes de começar, certifique-se de que você possui:

Client ID - Seu identificador único de cliente
Client Secret - Chave secreta para autenticação
X-Tenant-Id - Seu identificador de tenant (ex.: tenant-suaempresa)

informação

Se você ainda não possui credenciais, entre em contato com nossa equipe de suporte.

Ambientes

Ambiente	URL de Autenticação	URL da API	Observações
Sandbox (dev)	—	—	Temporariamente desativado.
Produção	`https://auth.api.corpx.com/oauth2/token`	`https://tenant.api.corpx.com`

Passo 1: Solicitar um Token de Acesso

Request

curl -X POST "https://auth.api.corpx.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`grant_type`	string	Sim	Sempre `client_credentials`
`client_id`	string	Sim	Seu identificador de cliente
`client_secret`	string	Sim	Sua chave secreta
`scope`	string	Não	Subconjunto dos escopos da credencial, separado por espaço. Omitir devolve um token com todos os escopos dela

Resposta de Sucesso (200 OK)

{
  "access_token": "eyJraWQiOiJ0emwzZWVYWGx1eVlDWHFwQXdBTzJWYWJNQ0llMFMyMXVRWGV2Y281N2RRPSIsImFsZyI6IlJTMjU2In0...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Campo	Descrição
`access_token`	Token JWT para autenticação nas chamadas à API
`expires_in`	Tempo de validade em segundos
`token_type`	Tipo do token (sempre `Bearer`)

Confie sempre no expires_in

O TTL não é o mesmo para todas as credenciais: as criadas pelo painel do backoffice valem 5 minutos (expires_in: 300), enquanto credenciais antigas, provisionadas manualmente, ainda valem 1 hora. Não fixe 3600 no seu cliente — leia o expires_in da resposta e renove com folga sobre ele.

Resposta de Erro (401 Unauthorized)

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Passo 2: Usar o Token nas Requisições

Com o token obtido, inclua-o no header Authorization de todas as requisições à API.

Exemplo: Consultar Saldo

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer eyJraWQiOiJ0emwzZWVYWGx1eVlDWHFwQXdBTzJWYWJNQ0llMFMyMXVRWGV2Y281N2RRPSIsImFsZyI6IlJTMjU2In0..." \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json"

Headers Obrigatórios

Header	Descrição
`Authorization`	Token de acesso no formato `Bearer {access_token}`
`X-Tenant-Id`	Seu identificador de tenant
`Content-Type`	`application/json` para requisições com body

Passo 3: Renovar o Token

O token expira após o tempo indicado em expires_in. Recomendamos:

Armazene o token em cache com o expires_in que veio na resposta
Renove antes de expirar — com TTL de 5 minutos, renovar no último minuto já é apertado
Trate o 403 de token expirado — a API responde 403 Forbidden, não 401; ao recebê-lo, obtenha um novo token e repita a chamada

Exemplo de Renovação Automática (Bash)

#!/bin/bash

# Variables
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH_URL="https://auth.api.corpx.com/oauth2/token"

# Function to get token
get_token() {
  response=$(curl -s -X POST "$AUTH_URL" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    -d "client_id=$CLIENT_ID" \
    -d "client_secret=$CLIENT_SECRET")
  
  echo "$response" | jq -r '.access_token'
}

# Get token
TOKEN=$(get_token)

# Use the token
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: tenant-suaempresa"

Exemplos Completos em Diferentes Linguagens

Python

import requests

# Credentials
CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_secret"
TENANT_ID = "tenant-suaempresa"

# Get token
auth_response = requests.post(
    "https://auth.api.corpx.com/oauth2/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET
    }
)

token = auth_response.json()["access_token"]

# Use the token
headers = {
    "Authorization": f"Bearer {token}",
    "X-Tenant-Id": TENANT_ID,
    "Content-Type": "application/json"
}

response = requests.get(
    "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance",
    headers=headers
)

print(response.json())

Node.js

const axios = require('axios');

const CLIENT_ID = 'your_client_id';
const CLIENT_SECRET = 'your_client_secret';
const TENANT_ID = 'tenant-suaempresa';

async function getToken() {
  const response = await axios.post(
    'https://auth.api.corpx.com/oauth2/token',
    new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET
    }),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
  );
  return response.data.access_token;
}

async function getBalance(accountId) {
  const token = await getToken();
  
  const response = await axios.get(
    `https://tenant.api.corpx.com/v1/accounts/${accountId}/balance`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Tenant-Id': TENANT_ID,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

Escopos de credencial

Cada credencial (client_id/client_secret) carrega um conjunto de escopos que define exatamente o que ela pode fazer. Você escolhe os escopos ao criar a credencial no painel do backoffice (seção API Credentials, disponível para usuários com perfil tenant manager).

Escopos que você mesmo concede:

Escopo	Libera
`read`	Consultas amplas da conta: saldo, extrato, timeline, lançamentos
`qrcode.manage`	QR code estático e dinâmico: criar, cancelar e consultar o pagamento do próprio QR
`pix_keys.manage`	Chaves PIX: listar, criar e excluir
`webhooks.manage`	Assinaturas de webhook, entregas e reenvio
`exports.create`	Exports de extrato: criar, acompanhar e baixar
`med.defend`	MED: consultar, responder e anexar evidências (não decide a devolução)

Cada escopo já consulta o próprio domínio. É o que permite uma credencial de recebimento que emite QR code e vê se ele foi pago sem ter acesso ao saldo e ao extrato: basta conceder qrcode.manage sozinho. Marque read apenas quando a credencial precisar realmente das consultas amplas da conta.

Escopos que movimentam dinheiro são emitidos pela CorpX, nunca pelo painel:

Escopo	Libera
`pix_out.create`	PIX out em todas as variantes (`/pix/out/*`), com o status dos próprios pagamentos
`refund.create`	Devolução de PIX recebido, com o status das próprias devoluções
`internal_transfer.create`	Transferência interna, com o lookup do destino
`ted.create`	TED, com o status das próprias transferências
`boleto_payment.create`	Preview, pagamento e status de boleto
`med.decide`	Decidir a devolução de um MED

Se você pedir um desses escopos pelo painel, a criação é recusada com 403 scope_not_self_service — fale com o suporte para emitirmos a credencial.

Restrição por conta

Uma credencial pode ficar restrita a contas específicas do seu tenant. É o caminho para, por exemplo, dar a um subsistema uma credencial que só emite QR code de uma conta. Chamadas a contas fora do conjunto respondem 403 forbidden — o erro genérico de permissão, sem insufficient_scope: o escopo está lá, a conta é que não. A mensagem não distingue conta inexistente de conta fora do conjunto, de propósito.

Combinando as duas dimensões: qrcode.manage + uma única conta resulta numa credencial que cobra por QR code naquela conta e não enxerga mais nada — nem o saldo dela, nem as outras contas do tenant.

Quando falta escopo

Se a credencial não tem o escopo da rota, a API responde 403 Forbidden nomeando o que falta:

{ "errorCode": "insufficient_scope", "message": "esta credencial não tem escopo para esta operação; é necessário o escopo qrcode.manage" }

Credenciais emitidas antes dos escopos granulares continuam funcionando sem alteração: elas mantêm o par grosso (api2/read api2/write) e acesso total.

Acesso suspenso por pendência

Quando existe uma pendência em aberto com a CorpX, o acesso do tenant pode ser suspenso temporariamente. A suspensão não invalida sua credencial: o mesmo client_id/client_secret continua obtendo token normalmente, e a recusa vem na chamada à API.

Estado	O que continua funcionando	Resposta nas demais chamadas
Suspenso	Consultas (`GET`) — saldo, extrato, status de operações	`403 tenant_suspended` nas escritas
Desativado	Nada	`403 tenant_disabled` em todas as rotas

{ "errorCode": "tenant_suspended", "message": "há uma pendência em aberto: operações de escrita estão suspensas até a regularização, consultas seguem disponíveis" }

Dois pontos importantes:

O dinheiro não para. PIX recebido continua sendo creditado, e você continua recebendo os webhooks desses eventos. O que a suspensão bloqueia é iniciar novas operações.
Reativar é imediato. Assim que a pendência é regularizada, o acesso volta na chamada seguinte — não é preciso gerar credencial nova nem novo token.

O motivo da pendência não vem no corpo do erro: ele aparece no painel do backoffice, para os operadores do seu time.

Erros Comuns

Erro	Causa	Solução
`invalid_client`	Client ID ou Secret incorretos	Verifique suas credenciais
`invalid_grant`	Tipo de grant inválido	Use `client_credentials`
`401 Unauthorized`	Header `Authorization` ausente	Envie `Authorization: Bearer <token>`
`403 Forbidden` (token inválido/expirado)	Token expirado, inválido ou assinatura incorreta	Obtenha um novo token. Note que expiração é `403`, não `401`
`403 insufficient_scope`	Credencial sem o escopo da rota	Crie uma credencial com o escopo indicado na mensagem
`403 tenant_suspended`	Pendência em aberto: escrita suspensa	Regularize com o suporte CorpX; consultas seguem disponíveis
`403 tenant_disabled`	Tenant desativado	Fale com o suporte CorpX para reativar
`403 forbidden`	Token válido, mas sem permissão nesse tenant ou nessa conta	Verifique o `X-Tenant-Id` e se a credencial está restrita a outras contas

Boas Práticas

Nunca exponha o client_secret em código client-side (frontend)
Use variáveis de ambiente para armazenar credenciais
Implemente cache de token para evitar requisições desnecessárias
Monitore a expiração e renove tokens de forma proativa
Use HTTPS para todas as comunicações

Próximos Passos

Agora que você sabe como autenticar, explore os outros guias:

Guia de QR Code Dinâmico - Gerar cobranças PIX
Guia de Cash Out - Fazer transferências PIX
Guia de Devolução - Solicitar estornos

Visão Geral​

Pré-requisitos​

Ambientes​

Passo 1: Solicitar um Token de Acesso​

Request​

Parâmetros​

Resposta de Sucesso (200 OK)​

Resposta de Erro (401 Unauthorized)​

Passo 2: Usar o Token nas Requisições​

Exemplo: Consultar Saldo​

Headers Obrigatórios​

Passo 3: Renovar o Token​

Exemplo de Renovação Automática (Bash)​

Exemplos Completos em Diferentes Linguagens​

Python​

Node.js​

Escopos de credencial​

Restrição por conta​

Quando falta escopo​

Acesso suspenso por pendência​

Erros Comuns​

Boas Práticas​

Próximos Passos​