Authentication

Overview #

The Trackberry API uses token-based authentication. All API requests must include a valid API token in the request headers.

Getting Your API Token #

1. Sign in to Trackberry at trackberry.ag
2. Navigate to Settings in your organization
3. Find the API section
4. Click Generate API Token
5. Copy and securely store your token

Important: API tokens are shown only once. If you lose your token, you'll need to generate a new one.

Using Your Token #

Include the token in the Authorization header of every API request:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     https://trackberry.ag/api/v1/shipments

Example with Python #

import requests

headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://trackberry.ag/api/v1/shipments",
    headers=headers
)
print(response.json())

Example with Ruby #

require "net/http"
require "json"

uri = URI("https://trackberry.ag/api/v1/shipments")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_TOKEN"
request["Content-Type"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

Error Responses #

Rate Limits #

API requests are rate-limited to prevent abuse:

• 100 requests per minute per API token
• Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707667200

If you exceed the rate limit, wait until the X-RateLimit-Reset timestamp before retrying.

Token Security #

• Store tokens in environment variables, not in code
• Never commit tokens to version control
• Rotate tokens periodically
• Revoke tokens immediately if compromised
• Each token is scoped to a single organization