Authentication Guide
Authenticate with the destinationlab API using scoped API keys. Learn about key types, permission scopes, rate limits, and security best practices.
Make your first authenticated request
All API requests must include a valid API key in the Authorization header using the Bearer scheme.
1. Generate an API key
Navigate to Settings โ API Keys in your admin dashboard and click Create Key. Select the scopes your integration needs and set an optional expiration date. The full key is only shown once โ copy it immediately.
2. Add the Authorization header
curl -X GET https://api.destinationlab.io/v1/orders \ -H "Authorization: Bearer uk_live_a1b2c3d4e5f6..." \ -H "Content-Type: application/json"
3. Handle the response
{
"data": [...],
"pagination": {
"page": 1,
"total": 42
}
}{
"error": "Invalid or missing
API key"
}Two key types for different use cases
Admin Key
uk_live_...Full access to all API resources. Used for server-to-server integrations where you control the environment.
Customer Key
ck_live_...Restricted access for customer-facing integrations. Ideal for embedded widgets or partner portals.
Available scopes
Assign fine-grained permissions to each API key. Use module wildcards like orders:* to grant all actions within a module.
orders:readorders:writecustomers:readcustomers:writeproducts:readinvoices:readinvoices:writeitineraries:readitineraries:writewebhooks:readwebhooks:writesuppliers:read*Understanding rate limits
Every API response includes rate limit headers so you can monitor your usage in real time. When you exceed the limit, the API returns a 429 Too Many Requests response.
HTTP/1.1 200 OK X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 847 X-RateLimit-Reset: 2026-01-15T14:00:00.000Z
X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetRetry-AfterBest practices
Rotate keys regularly
Generate new keys periodically and revoke old ones. Set expiration dates on keys for automatic rotation.
Use minimum scopes
Only grant the permissions your integration actually needs. A reporting dashboard only needs read scopes.
Keep keys server-side
Never expose API keys in client-side code, mobile apps, or public repositories. Use environment variables.
Monitor usage
Check the API usage dashboard for unusual patterns. Set up alerts for rate limit warnings and failed auth attempts.
Tenant-scoped data access
Every API key is bound to a specific tenant (organization). All queries are automatically filtered to return only your organization's data โ no cross-tenant access is possible.
How it works
- API keys are cryptographically bound to your tenant ID at creation
- Every database query is filtered by tenant_id โ enforced at the database level via Row Level Security
- Admin sessions include tenant context โ switching tenants requires re-authentication
- Customer portal sessions are scoped to both tenant and individual customer records
Security layers
Authentication error codes
Unauthorized
Missing or invalid API key. Check that your Authorization header uses the Bearer scheme with a valid key.
Forbidden
Your key does not have the required scope. Check which scopes are assigned to this key in the dashboard.
Too Many Requests
Rate limit exceeded. Back off and retry after the number of seconds specified in the Retry-After header.
ๆ ่กใชใใฌใผใทใงใณใๅน็ๅใใๆบๅใฏใงใใฆใใพใใ๏ผ
ไปๆฅใใ14ๆฅ้ใฎ็กๆใใฉใคใขใซใๅงใใพใใใใใฏใฌใธใใใซใผใไธ่ฆใใในใฆใฎๆฉ่ฝใซใใซใขใฏใปในใ