Authentication
Learn how to authenticate with the TariffLens API using API keys, manage test and live environments, and follow security best practices.
Overview
All TariffLens API requests must be authenticated using a Bearer token in the Authorization header. API keys are scoped to your organization and can be managed from the TariffLens dashboard.
Authorization: Bearer tlk_live_xxxxxxxxxxxxxxxxxxxxxAPI Key Types
TariffLens provides two types of API keys for different stages of your integration:
| Key Type | Prefix | Environment | Purpose |
|---|---|---|---|
| Live | tlk_live_ | Production | Real classifications against the live HTS database |
| Test | tlk_test_ | Sandbox | Development and testing with simulated responses |
When using test keys, send requests to https://api.sandbox.tarifflens.ai instead of the production URL. Test keys will not work against the production API and vice versa.
Getting Your API Key
Navigate to API settings
Log into your TariffLens dashboard and go to Settings → API.
Create a new key
Click Create API Key. Give it a descriptive name (e.g., "Production Backend" or "Staging Server") so you can identify it later.
Copy and store securely
Your full API key is shown only once at creation time. Copy it and store it in a secure location such as a secrets manager or environment variable.
You cannot retrieve the full key after creation. If you lose it, you'll need to revoke the key and create a new one.
Making Authenticated Requests
Include your API key as a Bearer token in the Authorization header of every request:
curl -X POST https://api.tarifflens.ai/api/v1/products/classify \
-H "Authorization: Bearer tlk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"product": {
"name": "Wireless Bluetooth Headphones",
"description": "Over-ear noise cancelling headphones"
},
"schedules": ["US-HTS"]
}'Using environment variables
Store your API key in an environment variable to avoid hardcoding it:
export TARIFFLENS_API_KEY="tlk_live_xxxxx"
curl -X POST https://api.tarifflens.ai/api/v1/products/classify \
-H "Authorization: Bearer $TARIFFLENS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"product": {"name": "Servo Motor", "description": "Brushless AC, 2.5kW"}, "schedules": ["US-HTS"]}'Example in Node.js
const response = await fetch(
"https://api.tarifflens.ai/api/v1/products/classify",
{
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.TARIFFLENS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
product: {
name: "Wireless Bluetooth Headphones",
description: "Over-ear noise cancelling headphones",
},
schedules: ["US-HTS"],
}),
}
);
const data = await response.json();
console.log(data.product_id); // "product_abc123xyz"
console.log(data.classifications[0].id); // "clf_def456"Example in Python
import os
import requests
response = requests.post(
"https://api.tarifflens.ai/api/v1/products/classify",
headers={
"Authorization": f"Bearer {os.environ['TARIFFLENS_API_KEY']}",
"Content-Type": "application/json",
},
json={
"product": {
"name": "Wireless Bluetooth Headphones",
"description": "Over-ear noise cancelling headphones",
},
"schedules": ["US-HTS"],
},
)
data = response.json()
print(data["product_id"]) # "product_abc123xyz"
print(data["classifications"][0]["id"]) # "clf_def456"Authentication Errors
If authentication fails, the API returns one of these error responses:
| Status Code | Error | Cause |
|---|---|---|
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Valid key but insufficient permissions, or key used against the wrong environment |
429 | Too Many Requests | Rate limit exceeded for this API key |
Example error response
{
"error": {
"type": "authentication_error",
"message": "Invalid API key provided.",
"code": "invalid_api_key"
}
}Rate Limiting
API requests are rate-limited per API key. The default limit is 100 requests per minute. Rate limit information is included in every response via headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per minute |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit window resets |
If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your client to handle this gracefully.
Key Management
Rotating keys
To rotate an API key, create a new key in the dashboard, update your application to use the new key, then revoke the old key. You can have multiple active keys simultaneously to enable zero-downtime rotations.
Revoking keys
If a key is compromised, revoke it immediately from Settings → API in the dashboard. Revoked keys are rejected instantly — there is no grace period.
If you believe an API key has been exposed, revoke it immediately and create a replacement. All in-flight requests using the revoked key will fail with a 401 response.
Security Best Practices
Use environment variables
Never hardcode API keys in source code. Store them in environment variables or a secrets manager like AWS Secrets Manager or HashiCorp Vault.
Server-side only
Never expose API keys in client-side code (browser JavaScript, mobile apps). Always make API calls from your backend server.
Use test keys for development
Use tlk_test_ keys during development and CI/CD. Reserve tlk_live_ keys for production environments only.
Rotate regularly
Rotate API keys periodically and immediately after any team member with access leaves the organization.
Request Tracking
Every API response includes an X-Request-ID header with a unique identifier (e.g., req_abc123). Save this value when logging requests — include it when contacting support to help with debugging.
HTTP/1.1 200 OK
X-Request-ID: req_abc123
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1706140800
Content-Type: application/json