API tokens & scopes

How to create workspace API keys, understand scopes, and use them securely.

Overview

Voyant authenticates every API request with a workspace-scoped API key. Keys can optionally carry fine-grained scopes that the API enforces per-route.

If you don’t assign scopes to a key, it is treated as a legacy wide-open key. Scoped keys are recommended for production.

Create a key

1. Open workspace settings

   In the dashboard, go to Settings → API Keys.
2. Generate key

   Click Generate New Key, give it a descriptive name, and optionally choose scopes.
3. Copy and store

   Copy the key once and store it in a secure secrets manager or environment variable.

Using a key

curl https://api.voyantcloud.com/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"

Keys automatically determine workspace context; do not send workspace IDs for customer keys. Internal system keys may specify x-workspace-id when necessary.

Scopes

Routes declare required scopes (e.g., products:read, bookings:write). The middleware allows access when your key’s scopes match using:

• Exact match: products:read
• Resource wildcard: products:* (all actions on products)
• Action wildcard: *:read (read all resources)
• Global wildcard: * (full access)

Available scopes

Products & Catalog

• products:read - View products, itineraries, pricing
• products:write - Create and update products
• products:delete - Delete products
• collections:read / collections:write / collections:delete
• tags:read / tags:write / tags:delete
• drafts:read / drafts:write

Bookings & Customers

• bookings:read - View bookings
• bookings:write - Create and update bookings
• bookings:delete - Cancel bookings
• customers:read / customers:write / customers:delete
• payments:read / payments:write

Inventory & Departures

• inventory:read - View availability
• inventory:write - Update allocations
• departures:read / departures:write / departures:delete
• pricing:read / pricing:write

Media & Webhooks

• media:read / media:write / media:delete
• webhooks:read / webhooks:write / webhooks:delete

Scope templates

Use these predefined templates when creating keys in the dashboard:

Template	Scopes	Use case
Read Only	*:read	Reporting, analytics dashboards
Full Access	*	Admin integrations
Booking Management	bookings:*, customers:*, payments:read	Reservation systems
Product Catalog	products:*, inventory:*, media:*, drafts:*	CMS integrations

Some routes rely only on the base workspace authentication (no explicit scope) and don’t require additional scopes beyond a valid API key.

Rotation & revocation

Rotating keys is zero-downtime:

1. Create a new key

   Generate and deploy a new key to all services.
2. Verify

   Smoke test your integrations.
3. Revoke old key

   Revoke the old key in the dashboard.

Revocation is immediate. The dashboard also triggers a KV cache purge so the revoked key stops working right away.

Common errors

401 Unauthorized - Missing or invalid Authorization token

{ "error": "Unauthorized" }

Best practices

• Use separate keys per workspace (each workspace has its own keys)
• Use sandbox workspaces for development and testing
• Prefer scoped keys for live workspaces
• Store keys in a secrets manager; never commit to source control
• Rotate keys periodically
• Monitor usage and rate limits in the dashboard

Related

• Authentication basics
• API reference
• Webhooks