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
- Open the Trainly Dashboard
- Navigate to your project settings
- Copy your API Key (starts with
tk_) and Project ID (starts with proj_)
Python SDK
from trainly import TrainlyClient
client = TrainlyClient(
api_key="tk_live_abc123",
project_id="proj_xyz789",
)
export TRAINLY_API_KEY="tk_live_abc123"
export TRAINLY_PROJECT_ID="proj_xyz789"
from trainly import TrainlyClient
# Automatically reads from TRAINLY_API_KEY and TRAINLY_PROJECT_ID
client = TrainlyClient()
React SDK
import { TrainlyProvider } from '@trainly/react';
<TrainlyProvider apiKey="tk_live_abc123" projectId="proj_xyz789">
<App />
</TrainlyProvider>
Security Best Practices
Never commit API keys to source control. Always use environment variables.
- 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
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
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 |
