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

# Authentication

> Authenticate your API requests using API keys. All requests must include a valid API key.

## Getting Your API Key

<Steps>
  <Step title="Sign in to Sentrial">
    Go to [sentrial.com](https://sentrial.com/login).
  </Step>

  <Step title="Go to Settings → API Keys">
    Navigate to your organization settings.
  </Step>

  <Step title="Create a new API key">
    Click "Create API Key", name it, and copy the key immediately.
  </Step>
</Steps>

<Warning>
  **Store your API key securely.** API keys are only shown once. Store them in environment variables or a secrets manager. Never commit them to code.
</Warning>

## Using API Keys

### HTTP Header (Recommended)

Include your API key in the `Authorization` header:

```
Authorization: Bearer sentrial_live_xxxxxxxxxxxxx
```

### cURL Example

```bash theme={null}
curl -X POST https://api.sentrial.com/api/sdk/sessions \
  -H "Authorization: Bearer sentrial_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Session", "agentName": "test-agent", "userId": "user_123"}'
```

### Python SDK

```python theme={null}
import sentrial

# Option 1: Configure globally
sentrial.configure(api_key="sentrial_live_xxxxxxxxxxxxx")

# Option 2: Create client directly
from sentrial import SentrialClient
client = SentrialClient(api_key="sentrial_live_xxxxxxxxxxxxx")

# Option 3: Use environment variable (recommended)
# Set SENTRIAL_API_KEY in your environment
client = SentrialClient()  # Auto-reads from env
```

### TypeScript SDK

```typescript theme={null}
import { SentrialClient } from '@sentrial/sdk';

const client = new SentrialClient({
  apiKey: process.env.SENTRIAL_API_KEY
});
```

## API Key Format

Sentrial API keys follow this format:

```
sentrial_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

* `sentrial_` — prefix identifying Sentrial keys
* `live_` — environment (live for production)
* Random string — unique identifier

## Error Responses

### 401 Unauthorized

Missing or invalid API key.

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

### 403 Forbidden

API key doesn't have permission for this action.

```json theme={null}
{
  "error": "Forbidden",
  "message": "API key does not have access to this resource"
}
```

## Security Best Practices

* **Use environment variables** — Store API keys in env vars, not in code
* **Never commit keys** — Add `.env` to `.gitignore` and use secrets managers in CI/CD
* **Rotate keys regularly** — Create new keys periodically and revoke old ones
* **Use separate keys per environment** — Different keys for dev, staging, and production
* **Revoke compromised keys immediately** — If a key is exposed, delete it in Settings right away

## Next Steps

<CardGroup cols={2}>
  <Card title="Sessions API" icon="server" href="/api/sessions">
    Create and manage sessions.
  </Card>

  <Card title="Events API" icon="bolt" href="/api/events">
    Track events within sessions.
  </Card>
</CardGroup>