Authentication¶

The TopTickets API uses Bearer token authentication with API keys. This guide explains how authentication works and how to use it effectively.

Overview¶

All API requests must include an Authorization header with a valid API key:

Authorization: Bearer YOUR_API_KEY

API keys grant specific permissions (scopes) that determine what operations you can perform.

API Key Format¶

API keys follow a specific format that indicates the key type:

Example API key:

tt_admin_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0...

Making Authenticated Requests¶

Include your API key in the Authorization header:

curl -X GET "https://api.toptickets.app/v1/tickets" \
  -H "Authorization: Bearer tt_admin_abc123..." \
  -H "Content-Type: application/json"

import requests

API_KEY = "tt_admin_abc123..."

response = requests.get(
    "https://api.toptickets.app/v1/tickets",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
)

API Scopes¶

API keys are granted specific scopes that control access to resources. Scopes follow the format resource:action.

Available Scopes¶

Scope Requirements by Endpoint¶

Each endpoint requires specific scopes. If your API key lacks the required scope, you'll receive a 403 Forbidden error.

Example: To create a ticket, your key needs tickets:write. To add a comment, you need comments:write.

See the Scopes Reference for a complete mapping of endpoints to required scopes.

Role-Based Permissions¶

Your user role determines which scopes you can request when creating API keys.

Admin Role¶

Admins have full access and can create API keys with any scope:

• All read, write, and delete scopes
• No expiration required
• Can view and manage all API keys in the organization

Read-Only Admin Role¶

Read-only admins have restricted capabilities:

• Allowed scopes: Read-only scopes only (*:read)
• Forced expiration: Keys automatically expire after 72 hours
• Cannot edit keys: Cannot modify scopes or settings after creation
• Cannot revoke other keys: Can only view their own keys

See User Roles for complete role details.

Rate Limits¶

API requests are rate limited based on your key type:

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. See Rate Limits for details.

Security Best Practices¶

Keep Keys Secret¶

• Never share API keys in public repositories or client-side code
• Use environment variables to store keys
• Rotate keys periodically

Use Minimum Required Scopes¶

• Request only the scopes your integration needs
• Use read-only keys when you don't need write access

Set Expiration Dates¶

• Set expiration dates on keys for temporary integrations
• Review and rotate long-lived keys regularly

Error Responses¶

401 Unauthorized¶

The API key is missing, invalid, expired, or revoked.

{
  "detail": "Invalid API key"
}

Common causes:

• Missing Authorization header
• Malformed API key
• Expired key
• Revoked key

403 Forbidden¶

The API key is valid but lacks the required scope.

{
  "detail": "Insufficient permissions. Required scope: tickets:write"
}

Solution: Create a new API key with the required scope, or use a key that already has it.

429 Too Many Requests¶

You've exceeded the rate limit.

{
  "detail": "Rate limit exceeded. Try again in 30 seconds."
}

Solution: Wait and retry with exponential backoff. Consider caching responses where possible.

Testing Your API Key¶

Use the test endpoint to verify your API key is working:

curl -X GET "https://api.toptickets.app/v1/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.toptickets.app/v1/test",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

print(response.json())

Success response:

{
  "status": "ok",
  "message": "API key is valid",
  "key_prefix": "tt_admin_abc",
  "scopes": ["tickets:read", "tickets:write"],
  "expires_at": "2025-04-15T00:00:00Z"
}

Next Steps¶

• Create API Keys - Learn how to create and manage keys
• API Scopes Reference - Complete scope documentation
• User Roles Reference - Role capabilities and restrictions