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 > API Keys
2. Click Create Key
3. Enter a name for the key (e.g., "Training Server")
4. 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 in a confirmation dialog:

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 a SHA-256 hash for a fast indexed lookup
• Full key values are never stored in plaintext

Using API Keys#

Environment Variable#

Set your key as an environment variable:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Validate and save the key using the YOLO CLI:

yolo login YOUR_API_KEY

Remove the saved key with yolo logout.

HTTP Headers#

Include the key in API requests:

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

See the REST API Reference for all available endpoints.

Remote Training#

Enable metric streaming with your key.

Install or update the Ultralytics package before starting:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
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 on the Settings > API Keys tab:

Each key card shows the key name, copyable key value, relative creation time, usage count, 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.104

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 when you need isolated inference capacity

FAQ#