> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baytos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Claro API using API keys

# 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

<Steps>
  <Step title="Navigate to API Keys">
    Log into [Claro](https://claro.baytos.ai) and click **API Keys** from the sidebar
  </Step>

  <Step title="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
  </Step>

  <Step title="Save Your Key Securely">
    Copy the API key immediately - it will only be shown once

    <Warning>
      Store your API key securely. Never commit it to version control or share it publicly.
    </Warning>
  </Step>
</Steps>

## Using API Keys

### Environment Variables (Recommended)

Store API keys in environment variables:

```bash theme={null}
# Add to your shell profile (.bashrc, .zshrc, etc.)
export BAYT_API_KEY="your_api_key_here"
```

Then in your code:

```python theme={null}
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:

```bash .env theme={null}
BAYT_API_KEY=your_api_key_here
```

Load it with python-dotenv:

```python theme={null}
from dotenv import load_dotenv
import os
from baytos.claro import BaytClient

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

<Warning>
  Add `.env` to your `.gitignore` to prevent accidentally committing secrets
</Warning>

### Direct Initialization (Not Recommended)

You can pass the API key directly, but this is not recommended for production:

```python theme={null}
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

<Note>
  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.
</Note>

## REST API Authentication

When using the REST API directly, include your API key in the `Authorization` header:

```bash theme={null}
curl https://api.baytos.ai/v1/prompts \
  -H "Authorization: Bearer your_api_key_here"
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Rotate API Keys Regularly" icon="rotate">
    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
  </Accordion>

  <Accordion title="Use Separate Keys per Environment" icon="layer-group">
    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.
  </Accordion>

  <Accordion title="Monitor API Key Usage" icon="chart-line">
    Check your API key usage regularly in **Settings → Security**:

    * Last used timestamp
    * Request count
    * Error rates

    Unusual activity may indicate a compromised key.
  </Accordion>

  <Accordion title="Restrict Access" icon="lock">
    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
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Invalid API Key Error

```python theme={null}
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:**

```python theme={null}
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

```python theme={null}
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

<Steps>
  <Step title="Creation">
    API keys are created in workspace security settings
  </Step>

  <Step title="Active">
    Keys remain active until explicitly revoked or deleted
  </Step>

  <Step title="Revocation">
    Revoked keys immediately stop working across all applications
  </Step>
</Steps>

<Note>
  There is no automatic expiration for API keys. Implement your own rotation policy based on your security requirements.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/sdk/python/installation">
    Install and configure the Python SDK with your API key
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Learn about REST API endpoints and authentication
  </Card>
</CardGroup>