Authentication

Learn how to authenticate your API requests using API keys.

Overview

Generation and account APIs require authentication. Public discovery includes health, capabilities, and OpenAPI; bot registration bootstraps credentials without an existing key. Vydra uses Bearer API keys for application requests.

API Key Format

API keys follow the format: vydra_live_[prefix]_[randomString]

Creating API Keys

You can create API keys from your dashboard or via the API itself (session authentication required).

Via Dashboard

Sign in to your Vydra account
Navigate to Settings → API Keys
Click Create New Key
Give your key a name and optional expiration
Copy and securely store your key - it will not be shown again!

Via API

Create API Keybash

curl -X POST https://vydra.ai/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=YOUR_SESSION_COOKIE" \
  -d '{
    "name": "My Production Key",
    "expiresInDays": 90
  }'

Important

The full API key is only returned once when created. Store it securely immediately. If you lose it, you will need to create a new key.

Agent onboarding and company workspaces

curl -X POST https://vydra.ai/api/v1/auth/bot-register \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"my-agent","billing_email":"ops@example.com","account_type":"company","company_name":"Example Company"}'

Ask whether the account is personal or for a company before registering. account_type accepts personal (default) or company; company_name is required for company accounts. The owner opens dashboard_url, chooses Connect workspace, and signs in with the verified billing email. This connects the existing credits, generations, and API keys to a regular login. Workspace & team lets administrators invite colleagues with their own logins. No new payment is required to claim.

Save api_key and dashboard_token when returned; they are shown once. dashboard_url and billing_url let a human manage the bot account and fund it. Use the API key for generation, not the dashboard token. If billing is unavailable on the deployment, billing_url can fall back to the dashboard. Returning a checkout link is not a successful payment.

Creator catalog, Studio, and library reads require jobs:read; writes require jobs:write. jobs:* or * also match. These resources belong to the key’s organization and share its credit balance. Human sign-in remains available through Clerk; existing bot accounts can use agent sign in.

Using API Keys

Include your API key in the Authorization header as a Bearer token:

Authentication Examples

curl https://vydra.ai/api/v1/models \
  -H "Authorization: Bearer vydra_live_user_abc_X7kM9pQ..."

API Key Response Format

When you create an API key, you will receive a response like this:

Create Key Responsejson

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "vydra_live_user_abc_X7kM9pQ...",
  "keyPrefix": "vydra_live_use...",
  "message": "Store this key securely. It will not be shown again."
}

Response Fields

Name	Type	Description
`id`	`string`	Unique identifier for the API key (UUID)
`key`	`string`	The full API key - only shown once!
`keyPrefix`	`string`	Truncated prefix for identification
`message`	`string`	Reminder to store the key securely

API Key Scopes

API keys can be restricted to specific operations using scopes. By default, keys are created with full access.

Scope	Description
`*`	Full access (default)
`models:*`	All model operations
`models:read`	List models only
`models:write`	Generate/edit with models
`jobs:*`	All job operations
`upload:*`	Upload files
`account:read`	Read account info

Managing API Keys

List Your Keys

curl https://vydra.ai/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Revoke a Key

curl -X DELETE https://vydra.ai/api/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Warning

Revoking an API key is permanent and cannot be undone. Any applications using the revoked key will immediately lose access.

Authentication Errors

These errors may occur during authentication:

Status	Code	Description
`401`	`MISSING_AUTH`	No Authorization header provided
`401`	`INVALID_FORMAT`	Invalid API key format
`401`	`KEY_NOT_FOUND`	API key does not exist
`401`	`KEY_REVOKED`	API key was revoked
`401`	`KEY_EXPIRED`	API key has expired
`403`	`INSUFFICIENT_SCOPE`	Key lacks required permission

Best Practices

🔐 Keep Keys Secret

Never expose API keys in client-side code, public repositories, or logs. Use environment variables to store keys securely.

🔄 Rotate Regularly

Periodically create new API keys and revoke old ones, especially if you suspect a key may have been compromised.

🎯 Use Minimal Scopes

Create keys with only the permissions they need. A key used only for listing models does not need write access.

📅 Set Expiration

For temporary integrations or testing, set an expiration date on your API keys to ensure they are automatically disabled.