Authentication Guide

This guide explains step by step how to obtain an access token to use the CorpX PIX API.

Overview

The CorpX API uses OAuth 2.0 with the Client Credentials flow for authentication. You will need your credentials (client_id and client_secret) to obtain a valid access token.

Prerequisites

Before you begin, make sure you have:

• Client ID - Your unique client identifier
• Client Secret - Secret key for authentication
• X-Tenant-Id - Your tenant identifier (e.g., tenant-suaempresa)

info

If you don't have credentials yet, contact our support team.

Environments

Environment	Authentication URL	API URL	Notes
Sandbox (dev)	—	—	Temporarily unavailable.
Production	https://auth.corpxapi.com/oauth2/token	https://api.corpxapi.com

Step 1: Request an Access Token

Request

curl -X POST "https://auth.corpxapi.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"

Parameters

Parameter	Type	Required	Description
grant_type	string	Yes	Always client_credentials
client_id	string	Yes	Your client identifier
client_secret	string	Yes	Your secret key

Success Response (200 OK)

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

Field	Description
access_token	JWT token for authentication in API calls
expires_in	Validity time in seconds (usually 3600 = 1 hour)
token_type	Token type (always Bearer)

Error Response (401 Unauthorized)

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

Step 2: Use the Token in Requests

With the obtained token, include it in the Authorization header of all API requests.

Example: Check Balance

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

Required Headers

Header	Description
Authorization	Access token in Bearer {access_token} format
X-Tenant-Id	Your tenant identifier
Content-Type	application/json for requests with a body

Step 3: Renew the Token

The token expires after the time indicated in expires_in. We recommend:

1. Store the token in cache with its expiration time
2. Renew before expiration - request a new token a few minutes in advance
3. Handle 401 errors - if you receive 401 Unauthorized, obtain a new token

Automatic Renewal Example (Bash)

#!/bin/bash

# Variables
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH_URL="https://auth.corpxapi.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://api.corpxapi.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: tenant-suaempresa"

Full Examples in Different Languages

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.corpxapi.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://api.corpxapi.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.corpxapi.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://api.corpxapi.com/v1/accounts/${accountId}/balance`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Tenant-Id': TENANT_ID,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

Common Errors

Error	Cause	Solution
invalid_client	Incorrect Client ID or Secret	Check your credentials
invalid_grant	Invalid grant type	Use client_credentials
401 Unauthorized	Expired or invalid token	Obtain a new token
403 Forbidden	Valid token but no permission	Check the X-Tenant-Id

Best Practices

1. Never expose the client_secret in client-side code (frontend)
2. Use environment variables to store credentials
3. Implement token caching to avoid unnecessary requests
4. Monitor expiration and renew tokens proactively
5. Use HTTPS for all communications

Next Steps

Now that you know how to authenticate, explore the other guides:

• Dynamic QR Code Guide - Generate PIX charges
• Cash Out Guide - Make PIX transfers
• Refund Guide - Request reversals