Authentication

Learn how to authenticate your API requests with workspace API keys

Overview

The Voyant API uses API keys for authentication. Each API key is scoped to a specific workspace and automatically filters all data access to that workspace context.

API keys provide complete access to your workspace data. Never share them publicly or commit them to version control.

API key format

API keys are workspace-scoped credentials that look like this:

voy_ws_1a2b3c4d5e6f7g8h9i0j

Each API key includes:

• Workspace ID: Automatically determined from the key
• Scopes: Optional permissions limiting API access
• Rate limits: Per-workspace request limits
• Status: Active or revoked

Authentication methods

Authorization header (recommended)

Pass your API key using the Authorization: Bearer <token> header with every request:

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

This is the recommended method as it keeps your API key out of URLs and query strings.

Internal API authentication

For internal services, you can use an internal API key with explicit workspace specification:

curl https://api.voyantcloud.com/v1/products \
  -H "Authorization: Bearer INTERNAL_API_KEY" \
  -H "x-workspace-id: ws_123abc"

Internal API keys are only available to Voyant system services and are not accessible to customers.

Managing API keys

Creating an API key

1. Access workspace settings

   Log in to your Voyant dashboard and navigate to workspace settings.

2. Go to API keys section

   Find the API Keys tab in your workspace settings.
3. Generate new key

   Click Generate New Key and provide a descriptive name (e.g., “Production API”, “Staging Environment”).

4. Copy and secure

   Copy the API key immediately. It will only be displayed once. Store it securely in your environment variables or secrets manager.

   Save the key in a password manager or environment variable immediately.

Rotating API keys

For security best practices, rotate your API keys periodically:

1. Generate new key

   Create a new API key before revoking the old one to avoid downtime.

2. Update applications

   Deploy the new key to all applications and services that use the API.

3. Verify functionality

   Test that all integrations work with the new key.
4. Revoke old key

   Once verified, revoke the old key from the workspace settings.

Keep both keys active during the transition period to ensure zero-downtime key rotation.

Revoking API keys

Immediately revoke an API key if:

• It has been exposed publicly
• An employee with access has left
• You’re migrating to a new key
• You suspect unauthorized access

Revoking an API key is immediate and cannot be undone. All requests with that key will fail instantly.

Propagation

Key changes take effect quickly across our platform. In most cases they are active immediately; allow up to about a minute for caches to refresh in edge locations.

• Revocations stop new requests right away; rotate keys during low-traffic windows to avoid client cache hiccups.
• Scoped keys enforce minimum permissions and support wildcards (products:*, *:read, *).
• For best results, update your applications first, verify, then revoke old keys.

Security best practices

Environment variables

Always store API keys in environment variables, never in code:

Node.js

// ✅ Correct - use environment variables
const apiKey = process.env.VOYANT_API_KEY;

// ❌ Wrong - never hardcode keys
const apiKey = "voy_ws_1a2b3c4d5e6f7g8h9i0j";

Python

import os

# ✅ Correct - use environment variables
api_key = os.environ['VOYANT_API_KEY']

# ❌ Wrong - never hardcode keys
api_key = "voy_ws_1a2b3c4d5e6f7g8h9i0j"

PHP

<?php
// ✅ Correct - use environment variables
$apiKey = getenv('VOYANT_API_KEY');

// ❌ Wrong - never hardcode keys
$apiKey = "voy_ws_1a2b3c4d5e6f7g8h9i0j";
?>

Server-side only

Never use API keys in client-side JavaScript, mobile apps, or any publicly accessible code.

API keys should only be used from secure server environments:

• ✅ Backend servers (Node.js, Python, PHP, Ruby, Go, etc.)
• ✅ Serverless functions (AWS Lambda, Cloudflare Workers, Vercel Functions)
• ✅ Internal services and microservices
• ❌ Frontend JavaScript (React, Vue, Angular)
• ❌ Mobile applications (iOS, Android)
• ❌ Desktop applications with embedded keys

HTTPS only

Always use HTTPS when making API requests to protect your API key in transit:

# ✅ Correct - HTTPS
https://api.voyantcloud.com/v1/products

# ❌ Wrong - HTTP (insecure)
http://api.voyantcloud.com/v1/products

Minimal permissions

When creating API keys, grant only the minimum required permissions:

• Use scoped keys for specific operations when available
• Use sandbox workspaces for development and testing
• Create separate keys for each workspace

Monitor key usage

Regularly review API key usage in your workspace settings:

• Check access logs for unusual patterns
• Monitor rate limit consumption
• Review which keys are actively used
• Revoke unused keys

Workspace context

All API operations are automatically scoped to the workspace associated with your API key:

# This request will only return products from your workspace
curl https://api.voyantcloud.com/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"

You never need to specify a workspace ID in API requests. The workspace context is automatically determined from your API key.

Multi-workspace access

If you need to access multiple workspaces, you must:

1. Generate a separate API key for each workspace
2. Use the appropriate key for each request
3. Manage keys separately in your application

Use environment variables with descriptive names for each workspace:

VOYANT_API_KEY_LIVE=voy_ws_live123...
VOYANT_API_KEY_SANDBOX=voy_ws_sandbox456...

Rate limiting

Rate limits depend on your workspace type:

Live workspaces:

• 3,000 requests per minute
• 30 requests per second burst

Sandbox workspaces:

• 100 requests per minute
• 5 requests per second burst

Pricing is usage-based—no tiers or enterprise upgrades required.

Rate limit headers are included in every response:

X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2988
X-RateLimit-Reset: 1704067200

Exceeding rate limits will result in 429 Too Many Requests responses. Implement exponential backoff in your application.

Error responses

Authentication errors return specific status codes:

401 Unauthorized - Missing or invalid Authorization Bearer token

{
  "error": "Unauthorized"
}

Testing authentication

Verify your API key works correctly:

cURL

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

A successful response with 200 OK confirms your API key is valid and working.

Troubleshooting

Common authentication issues

401 Unauthorized - Invalid API key

• Verify you copied the complete API key
• Check for extra spaces or line breaks
• Ensure the key hasn’t been revoked
• Confirm you’re using the correct header (Authorization) and Bearer scheme

429 Rate limit exceeded

• Implement request throttling in your application - Use exponential backoff for retries - Contact support for higher rate limits if needed - Cache responses when appropriate

Key rotation not working

• Ensure new key is active before revoking old one
• Check all services are using the new key
• Verify environment variables are updated
• Allow DNS/CDN cache to clear (up to 5 minutes)

Next steps

Quickstart

Make your first authenticated API request

Rate limits

Learn about rate limiting and best practices

API reference

Explore all available endpoints

Error handling

Handle authentication and other API errors