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

# Authentication

> Manage API keys and authenticate requests

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](https://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

<Warning>
  API keys are only displayed once when created. Store your key securely before closing the dialog.
</Warning>

### Via the API

Create keys programmatically using an existing key:

```bash theme={null}
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:

```json theme={null}
{
  "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
}
```

<Note>
  The full `key` value is only returned on creation. Store it securely.
</Note>

## Using API keys

Include the key in the `X-API-Key` header:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.relayai.dev/api/v1/datasets \
    -H "X-API-Key: rl_live_a1b2c3d4e5f6g7h8i9j0..."
  ```

  ```python Python theme={null}
  import requests

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

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.relayai.dev/api/v1/datasets", {
    headers: {
      "X-API-Key": "rl_live_a1b2c3d4e5f6g7h8i9j0..."
    }
  });
  ```
</CodeGroup>

## Listing API keys

View all keys for your account:

```bash theme={null}
curl https://api.relayai.dev/api/v1/auth/api-keys \
  -H "X-API-Key: $RELAY_API_KEY"
```

Response:

```json theme={null}
[
  {
    "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:

```bash theme={null}
curl -X DELETE https://api.relayai.dev/api/v1/auth/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $RELAY_API_KEY"
```

<Warning>
  Revoked keys cannot be restored. Any requests using a revoked key will receive a 401 Unauthorized response.
</Warning>

## Security best practices

### Environment variables

Never hardcode API keys in your source code. Use environment variables:

```bash theme={null}
# Set the environment variable
export RELAY_API_KEY="rl_live_a1b2c3d4e5f6g7h8i9j0..."
```

```python Python theme={null}
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`:

```text .gitignore theme={null}
.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:

```bash theme={null}
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

```json theme={null}
{
  "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 |