Authentication

You'll need to authenticate your requests to access any of the endpoints in the Odyssey API. In this guide, we'll look at how authentication works using API keys with scope-based permissions.

API Key authentication

Odyssey uses API keys to authenticate requests. Each API key has associated scopes that determine what resources and actions it can access. You can create and manage API keys from your organization dashboard.

Example request with API key

curl https://odysseylabs.ai/api/journeys/my-journey \
  -H "Authorization: Bearer {your_api_key}"

Always keep your API keys secure and never commit them to version control. If you suspect a key has been compromised, revoke it immediately and create a new one.

API key scopes

API keys use a scope-based permission system. When creating an API key, you grant it specific scopes that determine what it can access:

Journey scopes

  • journeys:read - Read journey configurations, steps, and analytics
  • journeys:write - Create and update journeys and steps

Analytics scopes

  • ingest:write - Send event data to the analytics ingest endpoint

Simulation scopes (coming soon)

  • simulations:run - Execute journey simulations and what-if analyses

Memo scopes (coming soon)

  • memos:read - Read decision memos
  • memos:write - Create and update decision memos

Organization scopes

  • org:settings - Manage organization settings
  • org:billing - Manage billing and subscriptions
  • members:manage - Add, remove, and manage organization members
  • results:read - Read simulation results and analytics

Creating an API key

To create an API key:

  1. Navigate to your organization dashboard
  2. Go to Settings → API Keys
  3. Click Create API Key
  4. Give your key a descriptive name
  5. Select the scopes you need
  6. (Optional) Set an expiration date
  7. Click Create

Your API key will be displayed once. Make sure to copy it and store it securely - you won't be able to see it again.

Using API keys in requests

Include your API key in the Authorization header of your requests using the Bearer authentication scheme:

Authentication header

Authorization: Bearer odyssey_live_1234567890abcdef

Here's a complete example of creating a journey:

Example: Create a journey

curl -X POST https://odysseylabs.ai/api/journeys/create \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "grant-application",
    "displayName": "Grant Application Form",
    "sourceSystem": "custom",
    "allowedOrigins": ["https://yourdomain.com"]
  }'

API key best practices

  • Name
    Use descriptive names
    Description

    Name your keys based on their purpose: "Production CI/CD", "Development Testing", "Partner Integration", etc.

  • Name
    Follow least privilege
    Description

    Only grant the minimum scopes required for each key's intended use.

  • Name
    Set expiration dates
    Description

    For temporary integrations or testing, set expiration dates on your keys.

  • Name
    Rotate regularly
    Description

    For production keys, rotate them periodically (e.g., every 90 days).

  • Name
    Use environment variables
    Description

    Store API keys in environment variables, never hardcode them in your application.

Error responses

If authentication fails, you'll receive an appropriate error response:

Unauthorized (401)

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

Forbidden (403)

{
  "error": "API key does not have required scope: journeys:write"
}

Rate limiting

API keys are subject to rate limiting based on your organization's plan. Rate limit headers are included in every response:

  • X-RateLimit-Limit - Your rate limit ceiling
  • X-RateLimit-Remaining - Number of requests remaining
  • X-RateLimit-Reset - Unix timestamp when the rate limit resets

If you exceed your rate limit, you'll receive a 429 Too Many Requests response. Contact support to request a rate limit increase for your organization.

Was this page helpful?