Developer Guide

Authentication Guide

Authenticate with the destinationlab API using scoped API keys. Learn about key types, permission scopes, rate limits, and security best practices.

Request API access Back to API docs

API Documentation

Getting Started

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

200 OK

{
  "data": [...],
  "pagination": {
    "page": 1,
    "total": 42
  }
}

401 Unauthorized

{
  "error": "Invalid or missing
            API key"
}

Key Types

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.

Scopes:All scopes available (configurable)

Rate limit:Tenant-level limits (default 1,000/hr)

Customer Key

ck_live_...

Restricted access for customer-facing integrations. Ideal for embedded widgets or partner portals.

Scopes:Explicitly assigned per key

Rate limit:Per-key limits (default 100/hr)

Permissions

Available scopes

Assign fine-grained permissions to each API key. Use module wildcards like orders:* to grant all actions within a module.

Scope

Description

orders:read

Read order data

orders:write

Create and update orders

customers:read

Read customer records

customers:write

Create and update customers

products:read

Read products and tours

invoices:read

Read invoice data

invoices:write

Generate invoices

itineraries:read

Read itineraries

itineraries:write

Create itineraries

webhooks:read

List webhook subscriptions

webhooks:write

Create and manage webhooks

suppliers:read

Read supplier records

*

Wildcard — grants all permissions

Rate Limiting

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

Header

Description

X-RateLimit-Limit

Maximum requests allowed per hour

X-RateLimit-Remaining

Requests remaining in the current window

X-RateLimit-Reset

ISO timestamp when the limit resets

Retry-After

Seconds to wait before retrying (only on 429)

Security

Best 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.

Data Isolation

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

API KeyTenant ID resolved from verified key

Session TokenTenant ID embedded in HMAC-signed token

Database (RLS)Row Level Security policies on all tables

ApplicationTenant context set per-request before data access

Error Reference

Authentication error codes

401

Unauthorized

Missing or invalid API key. Check that your Authorization header uses the Bearer scheme with a valid key.

403

Forbidden

Your key does not have the required scope. Check which scopes are assigned to this key in the dashboard.

429

Too Many Requests

Rate limit exceeded. Back off and retry after the number of seconds specified in the Retry-After header.

Jetzt starten

Bereit, Ihre Reiseoperationen zu optimieren?

Starten Sie noch heute Ihre 14-tägige kostenlose Testversion. Keine Kreditkarte erforderlich. Voller Zugriff auf alle Funktionen.

Kostenlos testen Demo buchen