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

Navigate to API Keys

Log into Claro and click API Keys from the sidebar

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

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

Environment Variables (Recommended)

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

Direct Initialization (Not Recommended)

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 API Keys Regularly

Rotate your API keys every 90 days or immediately if compromised:

Create a new API key
Update your applications with the new key
Delete the old API key

Use Separate Keys per Environment

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.

Monitor API Key Usage

Check your API key usage regularly in Settings → Security:

Last used timestamp
Request count
Error rates

Unusual activity may indicate a compromised key.

Restrict Access

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

Creation

API keys are created in workspace security settings

Active

Keys remain active until explicitly revoked or deleted

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.

Getting Started

Python SDK

Examples

Guides

Authentication

Authentication

Creating an API Key

Using API Keys

Environment Variables (Recommended)

.env Files (Development)

Direct Initialization (Not Recommended)

API Key Permissions

REST API Authentication

Security Best Practices

Troubleshooting

Invalid API Key Error

Permission Denied Error

API Key Lifecycle

Next Steps

Python SDK

API Reference

​Authentication

​Creating an API Key

​Using API Keys

​Environment Variables (Recommended)

​.env Files (Development)

​Direct Initialization (Not Recommended)

​API Key Permissions

​REST API Authentication

​Security Best Practices

​Troubleshooting

​Invalid API Key Error

​Permission Denied Error

​API Key Lifecycle

​Next Steps

Python SDK

API Reference

Authentication

Creating an API Key

Using API Keys

Environment Variables (Recommended)

.env Files (Development)

Direct Initialization (Not Recommended)

API Key Permissions

REST API Authentication

Security Best Practices

Troubleshooting

Invalid API Key Error

Permission Denied Error

API Key Lifecycle

Next Steps