# API keys

Create, store, and rotate the API keys your SDKs and integrations use to authenticate to Brizz.

Brizz uses API keys to authenticate SDKs and API requests.

This guide covers how to create keys, store them safely, and rotate them without downtime.

:::info
API keys are the legacy credential. New services should use a [Server DSN](/docs/admin/server-dsn.md), which carries the credential, the ingestion endpoint, and the service name in one string — so there's no separate app name to configure. Existing API keys keep working.
:::

## Creating API Keys

### Via Dashboard

1. Navigate to **Organization Settings** in the dashboard
2. Select the **API Keys** tab
3. Click **Create Telemetry API Key**
4. If your workspace offers a **Credential Type** choice, select **API Key** — it's marked *Legacy* there
5. Give the key a descriptive **Name** (e.g., "Production Server", "Local Development")
6. Set an **Expiry Duration**, or choose never to expire
7. Copy the key immediately — it won't be shown again

:::info
Keys can be created with an expiration date or configured to never expire. We recommend setting an expiration and rotating regularly.
:::

## Using API Keys

### Environment Variables (Recommended)

Store your API key in an environment variable:

```bash
export BRIZZ_API_KEY="your-api-key-here"
```

:::tip
Do not expose API keys in browser or mobile client code. In a browser, use a [Client DSN](/docs/admin/server-dsn.md#client-dsn); send mobile telemetry through a trusted server, since a Client DSN requires a browser `Origin` header.
:::

### Python

```python
import os
from brizz import Brizz

Brizz.initialize(
  api_key=os.environ["BRIZZ_API_KEY"],
  app_name="my-ai-app",
)
```

### TypeScript

```typescript
import { Brizz } from '@brizz/sdk';

Brizz.initialize({
  apiKey: process.env.BRIZZ_API_KEY!,
  appName: 'my-ai-app',
});
```

## API Key Best Practices

### DO ✅

- Use environment variables for API keys
- Rotate keys regularly (every 90 days recommended)
- Use separate keys for development and production
- Delete unused keys promptly

### DON'T ❌

- Commit API keys to version control
- Share keys between team members
- Expose keys in client-side code

## Rotating Keys

To rotate an API key without downtime:

1. Create a new API key
2. Update your application to use the new key
3. Verify the new key is working
4. Delete the old key

## Troubleshooting

### "Invalid API Key" Error

- Verify the key is copied correctly (no extra spaces)
- Check that the key hasn't been deleted
- Ensure you're using the correct environment

### "Expired" (or "Expiring Soon")

- If a key is expired, create a new one and update your environment variable
- Keep both keys active briefly during rollout to avoid downtime

## See also

- [Server DSN](/docs/admin/server-dsn.md) — the single-string alternative that carries the credential, endpoint, and service name together.
- [Sessions](/docs/instrument/sessions.md) — what to do once the key works.
- [Telemetry ingestion API](/docs/api/telemetry.md) — using the key without an SDK.
- [SSO (JumpCloud)](/docs/admin/sso-jumpcloud.md) — replace password login with SAML SSO.
- [PII & privacy](/docs/instrument/pii-and-privacy.md) — pairs with key rotation as part of a least-privilege posture.