> ## Documentation Index
> Fetch the complete documentation index at: https://docs.responsibleailabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> API key management, environment variables, rate limits, and security best practices.
All RAIL API requests are authenticated with API keys. Each key is scoped to an [application](/concepts/applications), and every evaluation made with it is governed by that application's policy. Keys appear in your usage logs.
To see which application a key belongs to and the policy governing it, call [`GET /config`](/api-reference/config).
```mermaid theme={null}
flowchart LR
App["Your Application"] -->|"Authorization: Bearer rail_..."| API["RAIL API"]
API -->|"200 + result"| App
API -->|"401 Invalid key"| App
API -->|"429 Rate limit"| App
```
## Getting an API key
[Create a free account](https://responsibleailabs.ai/register) at responsibleailabs.ai.
Go to your [Dashboard](https://responsibleailabs.ai/dashboard) and navigate to the **API Keys** section.
Click **Generate Key**. Keys start with `rail_` and are shown exactly once. Copy yours immediately.
Your key will not be shown again after you close the dialog. Store it securely before leaving the page.
## Using the API key
Pass your key as a Bearer token in the `Authorization` header on every request:
```
Authorization: Bearer YOUR_RAIL_API_KEY
```
Full cURL example:
```bash theme={null}
curl -X POST https://api.responsibleailabs.ai/railscore/v1/eval \
-H "Authorization: Bearer YOUR_RAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "Your AI-generated text here", "mode": "basic"}'
```
## SDK authentication
Both SDKs accept the API key at client construction and attach the header automatically:
```python Python theme={null}
from rail_score_sdk import RailScoreClient
import os
# Pass key directly (fine for scripts)
client = RailScoreClient(api_key="YOUR_RAIL_API_KEY")
# Recommended: read from environment variable
client = RailScoreClient(api_key=os.environ["RAIL_API_KEY"])
```
```typescript JavaScript theme={null}
import { RailScoreClient } from "@responsible-ai-labs/rail-score";
// Pass key directly
const client = new RailScoreClient({ apiKey: "YOUR_RAIL_API_KEY" });
// Recommended: read from environment variable
const client = new RailScoreClient({ apiKey: process.env.RAIL_API_KEY });
```
## Environment variables
Never hardcode API keys in source files. Use environment variables and keep keys out of version control.
```bash theme={null}
# .env — add to .gitignore, never commit this file
RAIL_API_KEY=YOUR_RAIL_API_KEY
```
```python theme={null}
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.environ["RAIL_API_KEY"]
```
Add via **Vercel Dashboard > Settings > Environment Variables**.
Variable name: `RAIL_API_KEY`
Never prefix the variable with `NEXT_PUBLIC_`. That would expose it in the browser bundle.
```typescript theme={null}
// Server-side only
const apiKey = process.env.RAIL_API_KEY;
```
```bash theme={null}
# Pass at runtime — never bake secrets into image layers
docker run -e RAIL_API_KEY=YOUR_RAIL_API_KEY my-app
# docker-compose.yml
services:
app:
image: my-app
environment:
- RAIL_API_KEY=${RAIL_API_KEY}
```
## Key management
You can create multiple keys for different environments (production, staging, CI). Manage all keys from your [dashboard](https://responsibleailabs.ai/dashboard).
| Action | When to use |
| ---------------- | --------------------------------------------------------------------------------------------- |
| **Generate key** | New environment, onboarding a new service, or rotating credentials on schedule |
| **Rename key** | Add context like "production-chatbot" or "staging-ci" for usage tracking |
| **Revoke key** | Suspected leak, employee offboarding, or decommissioning a service. Takes effect immediately. |
**Zero-downtime rotation:** Generate a new key, deploy it to your service and verify it works, then revoke the old key. Swapping takes seconds.
## Rate limits
Rate limits are applied per API key. Exceeding the limit returns HTTP 429.
| Plan | Requests / min | Requests / day |
| ---------- | -------------- | -------------- |
| Free | 10 | 100 |
| Pro | 60 | 5,000 |
| Business | 300 | 50,000 |
| Enterprise | Custom | Custom |
## Security best practices
* **Never expose keys in client-side code.** Browsers are public. Always call the API from your backend or serverless function.
* **Store keys in environment variables,** never hardcoded in source files or Docker images.
* **Add `.env` to `.gitignore`** before the first commit so keys are never accidentally pushed.
* **Use separate keys per environment.** If staging is compromised, production stays safe.
* **Revoke immediately if exposed.** Generate a replacement first, then revoke.
* **Rotate on a schedule.** Periodically regenerating keys limits the blast radius of any undetected leak.
## Auth error responses
| Status | Error | Fix |
| ------ | ----------------------------------------- | ---------------------------------------------------------- |
| `401` | Missing or malformed Authorization header | Add `Authorization: Bearer …` |
| `401` | Invalid API key | Verify the key starts with `rail_` and is copied correctly |
| `403` | API key revoked or inactive | Generate a new key from the dashboard |
| `429` | Rate limit exceeded | Reduce request frequency or upgrade plan |
## What's next
Make your first evaluation request in under 5 minutes.
Understand how credits are charged per call.
Full parameter reference for all endpoints.
Manage keys, view usage, and monitor credit balance.