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. Under Create a new API key, give the key a name (e.g., "Laptop") and create it
5. Copy the key and store it securely — new accounts start with no keys until you create one

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.dev/api/contracts/"

import httpx

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

const response = await fetch('https://tango.dev/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/o/authorize/'
token_url = 'https://tango.makegov.com/o/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.dev/api/contracts/')

OAuth2 Endpoints¶

Supported grant types: authorization_code, client_credentials, refresh_token.

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.dev/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

Some endpoints carry their own premium query budget in place of these limits, with its own headers (X-RateLimit-Premium-Limit, X-RateLimit-Premium-Remaining, X-RateLimit-Premium-Reset). Premium headers appear only on responses from endpoints with a premium budget.

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

Error Handling¶

Authentication Errors¶

401 Unauthorized¶

{
  "detail": "Authentication credentials were not provided."
}

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¶

Tier-gated endpoints return a structured tier_required error:

{
  "error": "This endpoint requires Small tier or above. Your current tier is Free.",
  "code": "tier_required",
  "required_tier": "Small",
  "current_tier": "Free",
  "upgrade_url": "https://docs.makegov.com/getting-started/pricing/"
}

Causes:

• The endpoint or filter requires a higher subscription plan than your current one

Solutions:

• Use required_tier, current_tier, and upgrade_url to surface an upgrade prompt programmatically
• See Plans & pricing for what each plan includes, or upgrade from the pricing page

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.