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

# Authentication

> Configure authentication for Trainly trace ingestion and multi-user apps

Trainly supports two authentication modes depending on your use case.

## API Key Authentication

**Recommended for most users.** API keys are the primary authentication method for sending traces to Trainly.

### Getting Your API Key

1. Open the [Trainly Dashboard](https://app.trainly.dev)
2. Navigate to your project settings
3. Copy your **API Key** (starts with `tk_`) and **Project ID** (starts with `proj_`)

### Python SDK

```python theme={null}
from trainly import TrainlyClient

client = TrainlyClient(
    api_key="tk_live_abc123",
    project_id="proj_xyz789",
)
```

Or set environment variables:

```bash theme={null}
export TRAINLY_API_KEY="tk_live_abc123"
export TRAINLY_PROJECT_ID="proj_xyz789"
```

```python theme={null}
from trainly import TrainlyClient

# Automatically reads from TRAINLY_API_KEY and TRAINLY_PROJECT_ID
client = TrainlyClient()
```

### React SDK

```tsx theme={null}
import { TrainlyProvider } from '@trainly/react';

<TrainlyProvider apiKey="tk_live_abc123" projectId="proj_xyz789">
  <App />
</TrainlyProvider>
```

### Security Best Practices

<Warning>
  Never commit API keys to source control. Always use environment variables.
</Warning>

* Store keys in environment variables (`TRAINLY_API_KEY`)
* Use `.env` files locally and secrets managers in production
* Keep API keys server-side whenever possible -- avoid exposing them in client-side bundles
* Rotate keys regularly from the dashboard settings page
* Use separate keys for development and production environments

## V1 OAuth Authentication

Use V1 OAuth when you are building a multi-user application and need:

* **Per-user data isolation** -- each user's traces are scoped to their identity
* **Embedded Trainly in your product** -- end-users authenticate with your existing auth provider

### Supported Providers

| Provider      | Configuration                                        |
| ------------- | ---------------------------------------------------- |
| Clerk         | Use `getToken({ template: 'trainly' })`              |
| Auth0         | Use `getAccessTokenSilently()` with Trainly audience |
| AWS Cognito   | Use the Cognito ID token                             |
| Firebase Auth | Use `getIdToken()`                                   |
| Custom OIDC   | Any provider with standard OIDC token endpoints      |

### React SDK

```tsx theme={null}
import { TrainlyProvider } from '@trainly/react';
import { useAuth } from '@clerk/nextjs';

function App() {
  const { getToken } = useAuth();

  return (
    <TrainlyProvider
      appId="app_abc123"
      projectId="proj_xyz789"
      getToken={() => getToken({ template: 'trainly' })}
    >
      <MyApp />
    </TrainlyProvider>
  );
}
```

### Python SDK

```python theme={null}
from trainly import TrainlyV1Client

client = TrainlyV1Client(
    user_token="eyJhbGciOi...",
    app_id="app_abc123",
)
```

### Feature Limitations

V1 OAuth mode has some restrictions compared to API key authentication:

| Feature           | API Key | V1 OAuth |
| ----------------- | ------- | -------- |
| Trace ingestion   | Yes     | Yes      |
| Trace scoring     | Yes     | Yes      |
| Session grouping  | Yes     | Yes      |
| Prompt versioning | Yes     | No       |
| Full analytics    | Yes     | Limited  |

## Choosing an Auth Mode

| Scenario                             | Recommended Mode |
| ------------------------------------ | ---------------- |
| Server-side trace ingestion          | API Key          |
| Single-developer project             | API Key          |
| CI/CD pipeline tracing               | API Key          |
| Multi-user SaaS with per-user traces | V1 OAuth         |
| Embedding Trainly in your product    | V1 OAuth         |