Skip to main content

​
Authentication

Claro uses API keys to authenticate requests. API keys are workspace-scoped and can be managed from your workspace settings.

​
Creating an API Key

1

Navigate to API Keys

Log into Claro and click API Keys from the sidebar
2

Create New API Key

Click Create API Key and provide a descriptive name:
  • Development - For local development
  • Production - For production deployments
  • CI/CD - For automated testing and deployments
3

Save Your Key Securely

Copy the API key immediately - it will only be shown once
Store your API key securely. Never commit it to version control or share it publicly.

​
Using API Keys

Store API keys in environment variables: 
# Add to your shell profile (.bashrc, .zshrc, etc.)
export BAYT_API_KEY="your_api_key_here"
Then in your code: 
import os
from baytos.claro import BaytClient

client = BaytClient(api_key=os.getenv("BAYT_API_KEY"))

​
.env Files (Development)

For local development, use a .env file:
.env
BAYT_API_KEY=your_api_key_here
Load it with python-dotenv: 
from dotenv import load_dotenv
import os
from baytos.claro import BaytClient

load_dotenv()
client = BaytClient(api_key=os.getenv("BAYT_API_KEY"))
Add .env to your .gitignore to prevent accidentally committing secrets
You can pass the API key directly, but this is not recommended for production: 
from baytos.claro import BaytClient

client = BaytClient(api_key="your_api_key_here")  # Not recommended

​
API Key Permissions

API keys have the following permissions by default:
  • prompts:read - Read prompts and their versions
  • prompts:list - List all prompts in the workspace
  • context:download - Download attached context files
API keys inherit the permissions of the user who created them. If you need different permissions, create the key from a user account with the appropriate access level.

​
REST API Authentication

When using the REST API directly, include your API key in the Authorization header: 
curl https://api.baytos.ai/v1/prompts \
  -H "Authorization: Bearer your_api_key_here"

​
Security Best Practices

Rotate your API keys every 90 days or immediately if compromised:
  1. Create a new API key
  2. Update your applications with the new key
  3. Delete the old API key
Create different API keys for each environment:
  • Development keys for local testing
  • Staging keys for pre-production
  • Production keys for live applications
This allows you to revoke compromised keys without affecting other environments.
Check your API key usage regularly in Settings → Security:
  • Last used timestamp
  • Request count
  • Error rates
Unusual activity may indicate a compromised key.
Follow the principle of least privilege:
  • Only give API keys to services that need them
  • Create keys from service accounts, not personal accounts
  • Delete unused API keys immediately

​
Troubleshooting

​
Invalid API Key Error

BaytAuthError: Invalid API key
Common causes:
  • API key not set or set incorrectly
  • Extra spaces or quotes around the key
  • API key was deleted or revoked
  • Using a key from a different workspace
Solution: 
import os
from baytos.claro import BaytClient

# Debug: Print the key (first few characters only)
api_key = os.getenv("BAYT_API_KEY")
print(f"API key starts with: {api_key[:10]}..." if api_key else "API key not set")

# Initialize client
client = BaytClient(api_key=api_key)

​
Permission Denied Error

BaytPermissionError: Insufficient permissions
Solution:
  • Verify the user who created the API key has the necessary permissions
  • Check workspace membership and roles
  • Create a new API key from an account with appropriate access

​
API Key Lifecycle

1

Creation

API keys are created in workspace security settings
2

Active

Keys remain active until explicitly revoked or deleted
3

Revocation

Revoked keys immediately stop working across all applications
There is no automatic expiration for API keys. Implement your own rotation policy based on your security requirements.

​
Next Steps

Python SDK

Install and configure the Python SDK with your API key

API Reference

Learn about REST API endpoints and authentication