Skip to main content

​
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
  • Bookings & Customers
  • Inventory & Departures
  • Media & Webhooks
  • 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

​
Scope templates

Use these predefined templates when creating keys in the dashboard:
TemplateScopesUse case
Read Only*:readReporting, analytics dashboards
Full Access*Admin integrations
Booking Managementbookings:*, customers:*, payments:readReservation systems
Product Catalogproducts:*, 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

{ "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