API Keys

Ultralytics Platform API keys enable secure programmatic access for remote training, inference, and automation. Create named keys with AES-256-GCM encryption for different use cases.

Create API Key

Create a new API key:

1. Go to Settings > Profile
2. Scroll to the API Keys section
3. Click Create Key
4. Enter a name for the key (e.g., "Training Server")
5. Click Create Key

Key Name

Give your key a descriptive name:

• training-server - For remote training machines
• ci-pipeline - For CI/CD integration
• local-dev - For local development

Key Display

After creation, the key is displayed once:

Key Format

API keys follow this format:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Prefix: ul_ identifies Ultralytics keys
• Body: 40 random hexadecimal characters
• Total: 43 characters

Key Security

• Keys are stored with AES-256-GCM encryption
• Authentication uses SHA-256 hash for fast prefix lookup and hash comparison
• Full key values are never stored in plaintext

Using API Keys

Environment Variable

Set your key as an environment variable:

export ULTRALYTICS_API_KEY="ul_your_key_here"

$env:ULTRALYTICS_API_KEY = "ul_your_key_here"

YOLO CLI

Set the key using the YOLO CLI:

yolo settings api_key="ul_your_key_here"

In Code

Use the key in your Python scripts:

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "ul_your_key_here"

HTTP Headers

Include the key in API requests:

curl -H "Authorization: Bearer ul_your_key_here" \
  https://platform.ultralytics.com/api/...

See the REST API Reference for all available endpoints.

Remote Training

Enable metric streaming with your key.

pip install "ultralytics>=8.4.14"

export ULTRALYTICS_API_KEY="ul_your_key_here"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

See Cloud Training for the complete remote training guide.

Manage Keys

View Keys

All keys are listed in Settings > Profile under the API Keys section:

Each key card shows the key name, the full decrypted key value (copyable), relative creation time, and a revoke button.

Revoke Key

Revoke a key that's compromised or no longer needed:

1. Find the key in the API Keys section
2. Click the Revoke (trash) button
3. Confirm revocation

Regenerate Key

If a key is compromised:

1. Create a new key with the same name
2. Update your applications
3. Revoke the old key

Workspace API Keys

API keys are scoped to the currently active workspace:

• Personal workspace: Keys authenticate as your personal account
• Team workspace: Keys authenticate within the team context

When switching workspaces in the sidebar, the API Keys section shows keys for that workspace. Editor role or higher is required to manage workspace API keys. See Teams for role details.

Security Best Practices

Do

• Store keys in environment variables
• Use separate keys for different environments
• Revoke unused keys promptly
• Rotate keys periodically
• Use descriptive names to identify key purposes

Don't

• Commit keys to version control
• Share keys between applications
• Log keys in application output
• Embed keys in client-side code

Key Rotation

Rotate keys periodically for security:

1. Create new key with same name
2. Update applications to use new key
3. Verify applications work correctly
4. Revoke old key

Troubleshooting

Invalid Key Error

Error: Invalid API key

Solutions:

1. Verify key is copied correctly (including the ul_ prefix)
2. Check key hasn't been revoked
3. Confirm environment variable is set
4. Ensure you're using ultralytics>=8.4.14

Permission Denied

Error: Permission denied for this operation

Solutions:

1. Verify you're the resource owner or have appropriate workspace access
2. Check the key belongs to the correct workspace
3. Create a new key if needed

Rate Limited

Error: Rate limit exceeded

Solutions:

1. Reduce request frequency — see the rate limit table for per-endpoint limits
2. Implement exponential backoff using the Retry-After header
3. Use a dedicated endpoint for unlimited inference throughput

FAQ

How many keys can I create?

There's no hard limit on API keys. Create as many as needed for different applications and environments.

Do keys expire?

Keys don't expire automatically. They remain valid until revoked. Consider implementing rotation for security.

Can I see my key after creation?

Yes, full key values are visible in the key list on Settings > Profile. The Platform decrypts and displays your keys so you can copy them anytime.

Are keys region-specific?

Keys work across regions but access data in your account's region only.

Can I share keys with team members?

Better practice: Have each team member create their own key. For team workspaces, each member with Editor role or higher can create keys scoped to that workspace.

📅 Created 1 month ago ✏️ Updated 6 days ago

Comments