> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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`)

> **Info**
>
> 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

```bash
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)

```json
{
  "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`)                |

> **Reutilize o token. Não peça um token por chamada.**
>
> O `access_token` vale **5 minutos** (`expires_in: 300`) e deve ser reutilizado
> em **todas** as chamadas até expirar. Gerar um token novo a cada request é
> **proibido**: esgota o Cognito, atrasa a sua integração e pode fazer a emissão
> ser recusada.
>
> Guarde o token no seu lado. Só chame `/oauth2/token` de novo quando faltar
> cerca de 60 segundos para o `expires_in` acabar, ou quando a API responder
> `403` de token expirado. Não fixe o TTL no cliente — leia o `expires_in` da
> resposta.

### Resposta de Erro (401 Unauthorized)

```json
{
  "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

```bash
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` (**5 minutos** nas
credenciais atuais). É **obrigatório** reutilizar o mesmo token até perto
desse prazo:

1. **Armazene o token** em cache com o `expires_in` que veio na resposta
2. **Renove antes de expirar** — com TTL de 5 minutos, renovar no último minuto já é apertado
3. **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)

```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

```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

```javascript
const axios = require('axios');

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

let cached = { token: null, expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt) {
    return cached.token;
  }
  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' } }
  );
  cached = {
    token: response.data.access_token,
    expiresAt: Date.now() + (response.data.expires_in - 60) * 1000
  };
  return cached.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, dinâmico, com vencimento e Pix Location: criar, confirmar, 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)                                                          |
| `kyc.read`             | Evidências KYC das próprias accreditations, **inclusive a biometria do titular**                                                |
| `accreditation.manage` | Criar e acompanhar accreditations (abertura de conta PF/PJ), sem saldo nem extrato                                              |

`kyc.read` é o único escopo de consulta que **não** é coberto por `read`: como
ele entrega rosto de cliente, precisa ser concedido explicitamente. A rota
também exige a feature `kyc_artifacts` habilitada no tenant — veja
[Arquivos comprobatórios](/baas/guias/abertura-de-contas/visao-geral#arquivos-comprobatórios).

**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                                              |
| `credentials.delegate`     | Emitir e revogar credenciais **de uma única conta**, assinadas — ver abaixo        |
| `pin.manage`               | Cadastrar, trocar e invalidar o PIN transacional dos operadores da conta           |
| `security_locks.manage`    | Configurar as travas de saída da conta (bloqueio, horário, IP)                     |

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.

### Credenciais delegadas

O escopo `credentials.delegate` é CorpX-only: a master do internet banking emite
filhas amarradas a uma conta. **Se você recebeu essa filha** (feature API do
IB), esta seção BaaS não é o seu guia — vá para
[Internet banking](/ib/guias/comece-aqui/primeiros-passos).

### 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:

```json
{ "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 |

```json
{ "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

1. **Reutilize o token** — um token por chamada é proibido
2. **Nunca exponha** o `client_secret` em código client-side (frontend)
3. **Use variáveis de ambiente** para armazenar credenciais
4. **Monitore a expiração** e renove tokens de forma proativa
5. **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](/baas/guias/receber/qr-code-dinamico) - Gerar cobranças PIX
* [Guia de Cash Out](/baas/guias/pagar/pix-out) - Fazer transferências PIX
* [Guia de Devolução](/baas/guias/pagar/devolucao) - Solicitar estornos