Skip to main content

​
API Keys

All requests to the Taxo API require authentication using an API key. This must be included in the Authorization header of each request. 
curl -X GET "https://api.taxo.co/v1/extractions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Getting your API Key

1

Sign in

Access the Taxo Dashboard with your business account
2

Go to settings

Navigate to Settings → API Keys in the sidebar menu
3

Create new API Key

Click on “Create API Key” and assign a descriptive name
4

Configure permissions

Select the necessary permissions for your integration
5

Copy and save

Copy the generated API key and store it securely
Important! The API key is only shown once during creation. Save it immediately in a secure location.

​
Environments

Taxo provides two environments for development and production:
  • Production
  • Staging
Base URL: https://api.taxo.co
  • Use for production applications
  • Real SAT data
  • 99.9% availability SLA
  • Production rate limits applied

​
Security best practices

Never hardcode your API key in source code. Use environment variables:
# .env
TAXO_API_KEY=your_api_key_here
TAXO_BASE_URL=https://api.taxo.co

// Correct ✅
const apiKey = process.env.TAXO_API_KEY;

// Incorrect ❌
const apiKey = "txo_live_abc123...";
  • Rotate your API keys regularly (recommended: every 90 days)
  • Create new keys before revoking old ones
  • Use multiple keys for different services when possible
  • Monitor key usage from the dashboard
For additional security, you can restrict API key usage to specific IPs:
  1. Go to Settings → API Keys in the dashboard
  2. Select the key you want to restrict
  3. Add allowed IPs in IP Restrictions
  4. Save changes
Configure alerts to detect anomalous usage:
  • Requests from unauthorized IPs
  • Unusual spikes in API usage
  • Multiple authentication errors
  • Usage exceeding normal limits

​
Handling authentication errors

try {
  const response = await fetch('https://api.taxo.co/v1/extractions', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  if (response.status === 401) {
    throw new Error('Invalid or expired API key');
  }
  
  if (response.status === 403) {
    throw new Error('Insufficient permissions for this endpoint');
  }
  
} catch (error) {
  console.error('Authentication error:', error.message);
  // Implement retry logic or notification
}

​
Common error codes

CodeErrorDescription
401UnauthorizedMissing, invalid, or expired API key
403ForbiddenValid API key but insufficient permissions for the resource
429Too Many RequestsYou have exceeded your plan’s rate limit
Tip: Implement retry logic with exponential backoff for 429 and 5xx errors, but never for 401 or 403 errors.

​
Verify authentication

You can verify that your API key works correctly using this endpoint: 
curl -X GET "https://api.taxo.co/v1/auth/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"
Successful response: 
{
  "valid": true,
  "organization": {
    "id": "org_123456",
    "name": "Mi Empresa S.A. de C.V."
  },
  "permissions": [
    "extractions:create",
    "extractions:read",
    "documents:download"
  ],
  "rateLimit": {
    "plan": "enterprise",
    "requestsPerHour": 1000,
    "remaining": 997
  }
}