Skip to main content

Authentication

Learn how to authenticate your API requests using vfrog.ai API keys.

Overview​

vfrog.ai uses API key authentication to secure access to the API. Every request must include a valid API key in the request headers.

API Keys​

API keys are unique identifiers that authenticate your requests to the vfrog.ai API. Each key is associated with your organization and can be managed through the vfrog.ai Console.

Creating an API Key​

  1. Log in to the vfrog.ai Console

  2. Navigate to API Keys in the sidebar

  3. Click Create API Key

  4. Configure your key:

    • Name: A descriptive name for the key
    • Description: Optional notes about the key's purpose
    • Monthly Quota: Set a usage limit (default: 10,000 requests/month)
    • Expiration: Optional expiration date
    • Classes: Restrict the key to specific data classes

  5. Click Create Key

  6. Important: Copy the API key immediately - it won't be shown again!

Using API Keys​

Include your API key in the x-api-key header of every request:

curl -X POST https://api.vfrog.ai/v1/cv/requests/sync \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "test-001", "image_url": "https://example.com/image.jpg"}'

Security Best Practices​

Keep Your Keys Secret​

  • ❌ Don't commit API keys to version control
  • ❌ Don't share keys in public forums or documentation
  • ❌ Don't embed keys in client-side code
  • ✅ Do use environment variables
  • ✅ Do rotate keys regularly
  • ✅ Do use different keys for different environments

Environment Variables​

Store your API key in environment variables:

Bash/Zsh:

export VFROG_API_KEY="your-api-key-here"

Python:

import os

api_key = os.environ.get('VFROG_API_KEY')

Node.js:

const apiKey = process.env.VFROG_API_KEY

Key Rotation​

Regularly rotate your API keys to maintain security:

  1. Create a new API key in the console
  2. Update your applications to use the new key
  3. Test thoroughly
  4. Revoke the old key

Managing API Keys​

Viewing Keys​

View all your API keys in the Console. You can see:

  • Key name and description
  • Creation date
  • Last used date
  • Current status (active, suspended, revoked)
  • Usage statistics

Updating Keys​

You can update the following properties of an existing key:

  • Name and description
  • Monthly quota
  • Expiration date
  • Class restrictions
note

You cannot change the actual key value. To get a new key value, create a new key.

Suspending Keys​

Temporarily disable a key without deleting it:

  1. Go to the API Keys page
  2. Click on the key you want to suspend
  3. Click Suspend Key

Suspended keys will return a 403 Forbidden error. You can resume the key at any time.

Revoking Keys​

Permanently disable a key:

  1. Go to the API Keys page
  2. Click on the key you want to revoke
  3. Click Revoke Key
  4. Confirm the action
warning

Revoked keys cannot be reactivated. You'll need to create a new key.

API Key Permissions​

Class Mapping​

Restrict API keys to specific data classes for fine-grained access control:

  1. When creating or editing a key, select the Classes tab
  2. Choose which classes this key can access
  3. Requests with this key will only process images for the selected classes

This is useful for:

  • Multi-tenant applications
  • Limiting access for third-party integrations
  • Separating production and development data

Authentication Errors​

401 Unauthorized​

Cause: Missing or invalid API key

Solution:

  • Ensure you're including the x-api-key header
  • Verify the key value is correct
  • Check that the key hasn't expired
{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

403 Forbidden​

Cause: Valid key but access denied

Reasons:

  • Key is suspended or revoked
  • Key doesn't have permission for the requested class
  • Organization account is suspended
{
  "error": "Forbidden",
  "message": "API key is suspended"
}

429 Too Many Requests​

Cause: Rate limit exceeded

Solution:

  • Wait before making more requests
  • Increase your monthly quota
  • Upgrade your plan
{
  "error": "Too Many Requests",
  "message": "Monthly quota exceeded"
}

Next Steps​