Authentication

Secure access to the TaxBridge API using API keys. We support both sandbox and live environments with environment-specific keys.

API Keys

TaxBridge uses Bearer token authentication. All API requests must include an Authorization header with your API key.

Sandbox Keys

Start with sk_test_ prefixed keys for development and testing.

sk_test_1234567890abcdef

Live Keys

Use sk_live_ prefixed keys for production fiscalization.

sk_live_abcdef1234567890

Making Authenticated Requests

# Using curl

curl -H "Authorization: Bearer sk_test_1234567890abcdef" \

https://api.taxbridge.com/v1/tax-intents

# Using JavaScript (fetch)

const response = await fetch('https://api.taxbridge.com/v1/tax-intents', {
  headers: {
    'Authorization': 'Bearer sk_test_1234567890abcdef',
    'Content-Type': 'application/json'
  }
});

# Using Python (requests)

import requests

response = requests.get(
  'https://api.taxbridge.com/v1/tax-intents',
  headers={
    'Authorization': 'Bearer sk_test_1234567890abcdef'
  }
)

Taxpayer Context

For operations that affect specific taxpayers, include the X-Tax-Payer-ID header to specify which taxpayer the request applies to.

Security Note

The API key determines the environment (sandbox/live), while the taxpayer ID scopes operations to a specific taxpayer under your account.

# Creating a tax intent for a specific taxpayer

curl -X POST https://api.taxbridge.com/v1/tax-intents \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "X-Tax-Payer-ID: tp_your_taxpayer_id" \
  -H "Content-Type: application/json" \
  -d '{"taxMethod": "DOMESTIC_STANDARD", ...}'

Error Responses

Authentication failures return standard HTTP status codes with descriptive messages.

401 Unauthorized

Missing or invalid Authorization header, or API key not found.

{"error": "Unauthorized", "message": "Invalid API Key"}

403 Forbidden

API key valid but doesn't have access to the requested resource.

{"error": "Forbidden", "message": "Access denied to this Taxpayer"}

Best Practices

1

Store Keys Securely

Never commit API keys to version control. Use environment variables or secure key management.

2

Use Sandbox for Testing

Always test integrations with sandbox keys before going live.

3

Rotate Keys Regularly

Generate new keys periodically and update your applications.