Authentication¶

The Tango API supports multiple authentication methods to suit different use cases and security requirements.

Authentication Methods¶

1. API Keys (Recommended)¶

API keys are the simplest and most secure method for server-to-server integration.

Getting an API Key¶

1. Visit Tango Web Interface
2. Sign up for an account or log in
3. Navigate to your account profile
4. Copy your API key (keep it secure!)

Using API Keys¶

Include your API key in the X-API-KEY header with every request:

curl -H "X-API-KEY: your-api-key-here" \
  "https://tango.makegov.com/api/contracts/"

import httpx

headers = {'X-API-KEY': 'your-api-key-here'}
response = httpx.get(
    'https://tango.makegov.com/api/contracts/',
    headers=headers
)

const response = await fetch('https://tango.makegov.com/api/contracts/', {
  headers: {
    'X-API-KEY': 'your-api-key-here'
  }
});

2. OAuth2¶

OAuth2 is recommended for web applications and user-specific integrations.

OAuth2 Flow¶

1. Register your application in the Tango web interface
2. Get client credentials (client ID and secret)
3. Implement OAuth2 flow in your application
4. Use access tokens for API requests

Example OAuth2 Implementation¶

import requests
from requests_oauthlib import OAuth2Session

# OAuth2 configuration
client_id = 'your-client-id'
client_secret = 'your-client-secret'
authorization_base_url = 'https://tango.makegov.com/oauth2/authorize/'
token_url = 'https://tango.makegov.com/oauth2/token/'

# Create OAuth2 session
oauth = OAuth2Session(client_id)

# Get authorization URL
authorization_url, state = oauth.authorization_url(authorization_base_url)

# Redirect user to authorization_url
print(f"Please go to {authorization_url} and authorize access")

# After authorization, get the authorization response URL
authorization_response = input('Enter the full callback URL: ')

# Fetch the access token
token = oauth.fetch_token(
    token_url,
    authorization_response=authorization_response,
    client_secret=client_secret
)

# Use the token for API requests
response = oauth.get('https://tango.makegov.com/api/contracts/')

OAuth2 Scopes¶

Available scopes for OAuth2 applications:

• read - Read access to all data

Monitoring Usage¶

Response Headers¶

Check these headers to monitor your API usage:

curl -I -H "X-API-KEY: your-api-key-here" \
  "https://tango.makegov.com/api/contracts/"

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 45
X-Execution-Time: 0.045s

Rate Limit Headers¶

• X-RateLimit-Limit: Total requests allowed for the most restrictive window
• X-RateLimit-Remaining: Requests remaining in the most restrictive window
• X-RateLimit-Reset: Seconds until reset for the most restrictive window
• X-Execution-Time: Request execution time

For the full list of per-window headers (daily/burst) and practical retry guidance, see the Rate limits guide.

Error Handling¶

Authentication Errors¶

401 Unauthorized¶

{
  "error": "AuthenticationFailed",
  "message": "Invalid API key",
  "code": 401
}

Causes:

• Missing API key
• Invalid API key
• Expired API key
• Inactive API key

Solutions:

• Check that you're including the X-API-KEY header
• Verify your API key is correct
• Ensure your API key is active
• Generate a new API key if needed

403 Forbidden¶

{
  "error": "InsufficientPermissions",
  "message": "You don't have permission to access this resource",
  "code": 403
}

Causes:

• Insufficient permissions for the requested resource
• Account type doesn't support the requested feature

Solutions:

• Check your account type and permissions
• Contact support to upgrade your account if needed

Rate Limit Errors¶

429 Too Many Requests¶

{
  "detail": "Rate limit exceeded for burst. Please try again in 45 seconds.",
  "wait_in_seconds": 45
}

Solutions:

• Wait for the rate limit window to reset
• Implement exponential backoff in your application
• Consider upgrading your account for higher limits
• Optimize your requests to reduce frequency

See the Rate limits guide for header semantics, examples (curl/Python/JS), and recommended client behavior.