Authentication

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

Sign in to app.relayai.dev
Navigate to Settings > API Keys
Click Create API Key
Enter a descriptive name (e.g., “Production Server”, “CI/CD Pipeline”)
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..."

import requests

headers = {"X-API-Key": "rl_live_a1b2c3d4e5f6g7h8i9j0..."}
response = requests.get("https://api.relayai.dev/api/v1/datasets", headers=headers)

const response = await fetch("https://api.relayai.dev/api/v1/datasets", {
  headers: {
    "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:

Create a new key
Update your applications to use the new key
Verify everything works
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

Issue	Solution
”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 code	Check for extra whitespace or encoding issues in the key

Getting Started

Guides

Concepts

SDKs

Authentication

API key basics

Creating API keys

Via the dashboard

Via the API

Using API keys

Listing API keys

Revoking API keys

Security best practices

Environment variables

Git ignore

Rotate keys regularly

Use descriptive names

Set expiration dates

Error responses

401 Unauthorized

Troubleshooting

​API key basics

​Creating API keys

​Via the dashboard

​Via the API

​Using API keys

​Listing API keys

​Revoking API keys

​Security best practices

​Environment variables

​Git ignore

​Rotate keys regularly

​Use descriptive names

​Set expiration dates

​Error responses

​401 Unauthorized

​Troubleshooting

API key basics

Creating API keys

Via the dashboard

Via the API

Using API keys

Listing API keys

Revoking API keys

Security best practices

Environment variables

Git ignore

Rotate keys regularly

Use descriptive names

Set expiration dates

Error responses

401 Unauthorized

Troubleshooting