authentication.mdx

title	Authentication
description	Secure your API requests with X-API-Key authentication.

API Keys

All API requests require authentication using an API key. Include your API key in the X-API-Key header of every request.

X-API-Key: bipa_prod_xxxxxxxxxxxx

Key types

Bipa provides two types of API keys:

Prefix	Environment	Purpose
bipa_prod_	Production	Real transactions with real money
bipa_test_	Sandbox	Testing and development

Never expose your API keys in client-side code, public repositories, or logs. Treat them like passwords.

Making authenticated requests

Include your API key in the X-API-Key header:

curl https://api.bipa.tech/v1/customers \
  -H "X-API-Key: bipa_prod_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

import requests

response = requests.get(
    "https://api.bipa.tech/v1/customers",
    headers={
        "X-API-Key": "bipa_prod_xxxxxxxxxxxx",
        "Content-Type": "application/json"
    }
)

const response = await fetch("https://api.bipa.tech/v1/customers", {
  headers: {
    "X-API-Key": "bipa_prod_xxxxxxxxxxxx",
    "Content-Type": "application/json"
  }
});

req, _ := http.NewRequest("GET", "https://api.bipa.tech/v1/customers", nil)
req.Header.Set("X-API-Key", "bipa_prod_xxxxxxxxxxxx")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, _ := client.Do(req)

Obtaining API keys

1. Log in to your Bipa Infra
2. Navigate to Developers → API Keys
3. Click Create new key
4. Copy your key immediately — it won't be shown again

You can only have one active API key at a time. Creating a new key will revoke the previous one.

Sandbox environment

The sandbox environment uses the same base URL but with test API keys:

curl https://api.bipa.tech/v1/customers \
  -H "X-API-Key: bipa_test_xxxxxxxxxxxx"

In sandbox mode:

• No real money is moved
• Pix payments are executed in Bacen staging environment
• Crypto transactions are executed in testnets

{/* TODO: update error response format

Authentication errors

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "doc_url": "https://docs.bipa.tech/errors#invalid_api_key"
  }
}

Common authentication issues:

Error Code	Cause	Solution
invalid_api_key	Key doesn't exist or is malformed	Check the key format and copy it again
revoked_api_key	Key has been revoked	Generate a new key in the Bipa Infra dashboard
missing_api_key	No X-API-Key header	Include the header in your request
*/}

Security best practices

Store API keys in environment variables, not in code: ```bash export BIPA_API_KEY=bipa_prod_xxxxxxxxxxxx ``` ```python import os api_key = os.environ.get("BIPA_API_KEY") ``` Create new keys periodically and revoke old ones. This limits the impact if a key is compromised. If you suspect a key has been compromised, create a new one immediately. This will automatically revoke the old key. Review your API logs in the Bipa Infra dashboard regularly to detect unusual activity.

{/* TODO: add IP allowlisting section */}