Skip to main content
Relay uses API keys to authenticate requests. Include your API key in the X-API-Key header of every request.

​
API key basics

API keys are tied to your tenant account and have full access to all resources within that account. Each key has:
  • Name: A label to identify the key’s purpose
  • Prefix: First 8 characters shown for identification (e.g., rl_live_a1b2...)
  • Scopes: Optional permission restrictions (coming soon)
  • Expiration: Optional expiration date

​
Creating API keys

​
Via the dashboard

  1. Sign in to app.relayai.dev
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Enter a descriptive name (e.g., “Production Server”, “CI/CD Pipeline”)
  5. Copy the key immediately
API keys are only displayed once when created. Store your key securely before closing the dialog.

​
Via the API

Create keys programmatically using an existing key: 
curl -X POST https://api.relayai.dev/api/v1/auth/api-keys \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expires_at": "2025-12-31T23:59:59Z"
  }'
Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Server",
  "key_prefix": "rl_live_",
  "key": "rl_live_a1b2c3d4e5f6g7h8i9j0...",
  "scopes": [],
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2025-12-31T23:59:59Z",
  "last_used_at": null
}
The full key value is only returned on creation. Store it securely.

​
Using API keys

Include the key in the X-API-Key header: 
curl https://api.relayai.dev/api/v1/datasets \
  -H "X-API-Key: rl_live_a1b2c3d4e5f6g7h8i9j0..."

​
Listing API keys

View all keys for your account: 
curl https://api.relayai.dev/api/v1/auth/api-keys \
  -H "X-API-Key: $RELAY_API_KEY"
Response: 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Server",
    "key_prefix": "rl_live_",
    "scopes": [],
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-12-31T23:59:59Z",
    "last_used_at": "2024-01-16T14:22:00Z"
  }
]

​
Revoking API keys

Revoke a key to immediately invalidate it: 
curl -X DELETE https://api.relayai.dev/api/v1/auth/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $RELAY_API_KEY"
Revoked keys cannot be restored. Any requests using a revoked key will receive a 401 Unauthorized response.

​
Security best practices

​
Environment variables

Never hardcode API keys in your source code. Use environment variables: 
# Set the environment variable
export RELAY_API_KEY="rl_live_a1b2c3d4e5f6g7h8i9j0..."
Python
import os

API_KEY = os.environ.get("RELAY_API_KEY")
if not API_KEY:
    raise ValueError("RELAY_API_KEY environment variable not set")

​
Git ignore

Add API key files to your .gitignore:
.gitignore
.env
.env.local
*.key

​
Rotate keys regularly

Create new keys periodically and revoke old ones:
  1. Create a new key
  2. Update your applications to use the new key
  3. Verify everything works
  4. Revoke the old key

​
Use descriptive names

Name keys by their purpose to make auditing easier:
  • “Production API Server”
  • “CI/CD Pipeline”
  • “Local Development - John’s Laptop”
  • “Monitoring Service”

​
Set expiration dates

For temporary or time-limited access, set an expiration: 
curl -X POST https://api.relayai.dev/api/v1/auth/api-keys \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contractor Access",
    "expires_at": "2024-03-31T23:59:59Z"
  }'

​
Error responses

​
401 Unauthorized

Returned when:
  • No X-API-Key header is provided
  • The API key is invalid or revoked
  • The API key has expired
{
  "detail": "Invalid or missing API key"
}

​
Troubleshooting

IssueSolution
”Invalid or missing API key”Verify the key is correct and hasn’t been revoked
”API key expired”Create a new key
Request works in curl but not in codeCheck for extra whitespace or encoding issues in the key