API credit fields and examples use integer ledger units: 50 units = 1 customer credit. Divide API amounts by 50 for display. See current customer pricing; historical examples are not price quotes.

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.