# API Keys and Scopes

> Create and manage API keys with fine-grained scopes, IP restrictions, CORS origin allowlists, and key expiration.

Source: https://0.0.0.0:8080/docs/api-keys-and-scopes

API keys authenticate programmatic access to the PromptRails API. Each key can be scoped to specific permissions, restricted by IP address and CORS origin, and configured with an expiration date.

## Creating API Keys

Create an API key from the PromptRails dashboard:

1. Open **Settings > API Keys**.
2. Select **Create API Key**.
3. Enter a name and choose the minimum required scopes.
4. Optionally add IP restrictions, allowed origins, and an expiration date.
5. Create the key and store the raw value securely.

The raw API key value is returned only at creation time. It is stored as a hash and cannot be retrieved later.

## Scopes

Scopes control what operations an API key can perform. PromptRails defines 24 granular scopes:

### Agent Scopes

| Scope            | Description                                    |
| ---------------- | ---------------------------------------------- |
| `agents:read`    | List and view agents and their versions        |
| `agents:write`   | Create, update, and delete agents and versions |
| `agents:execute` | Execute agents                                 |

### Prompt Scopes

| Scope             | Description                                     |
| ----------------- | ----------------------------------------------- |
| `prompts:read`    | List and view prompts and their versions        |
| `prompts:write`   | Create, update, and delete prompts and versions |
| `prompts:execute` | Execute prompts directly                        |

### Data Source Scopes

| Scope                  | Description                             |
| ---------------------- | --------------------------------------- |
| `data_sources:read`    | List and view data sources              |
| `data_sources:write`   | Create, update, and delete data sources |
| `data_sources:execute` | Execute data source queries             |

### Execution and Trace Scopes

| Scope             | Description                     |
| ----------------- | ------------------------------- |
| `executions:read` | List and view execution records |
| `traces:read`     | List and view trace spans       |

### Credential Scopes

| Scope               | Description                                    |
| ------------------- | ---------------------------------------------- |
| `credentials:read`  | List and view credentials (masked values only) |
| `credentials:write` | Create, update, and delete credentials         |

### Session and Chat Scopes

| Scope           | Description                    |
| --------------- | ------------------------------ |
| `sessions:read` | List and view chat sessions    |
| `chat:write`    | Send messages to chat sessions |

### Webhook Trigger Scopes

| Scope                    | Description                                 |
| ------------------------ | ------------------------------------------- |
| `webhook_triggers:read`  | List and view webhook triggers              |
| `webhook_triggers:write` | Create, update, and delete webhook triggers |

### Score Scopes

| Scope          | Description                                |
| -------------- | ------------------------------------------ |
| `scores:read`  | List and view scores and score configs     |
| `scores:write` | Create and update scores and score configs |

### Approval Scopes

| Scope             | Description                         |
| ----------------- | ----------------------------------- |
| `approvals:read`  | List and view approval requests     |
| `approvals:write` | Approve or reject approval requests |

### Asset Scopes

| Scope          | Description                            |
| -------------- | -------------------------------------- |
| `assets:read`  | List and view generated media assets   |
| `assets:write` | Delete assets and manage asset storage |

### Wildcard Scope

| Scope | Description                               |
| ----- | ----------------------------------------- |
| `*`   | Grants all permissions (use with caution) |

## IP Restrictions

Restrict API key usage to specific IP addresses or CIDR ranges when creating or editing the key in the dashboard. You can mix individual IPs and CIDR ranges, including IPv6 entries.

Requests from IPs not in the allowlist receive a `403 Forbidden` response.

## CORS Origin Restrictions

Restrict which web origins can use the API key by adding an allowlist in the dashboard. This is most relevant for browser-based applications.

## Key Expiration

Set an expiration date on API keys when creating or editing the key in the dashboard.

Expired keys are automatically rejected. Use `last_used_at` to identify stale keys.

## Key Format

API keys follow this format:

- **Full key**: Returned only at creation time (e.g., `pr_live_abc123...xyz789`)
- **Key prefix**: Stored and displayed for identification (e.g., `pr_live_ab`)
- **Key hash**: SHA-256 hash stored in the database for authentication

## Authentication

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

```bash
curl -H "X-API-Key: pr_live_abc123...xyz789" \
     https://api.promptrails.ai/api/v1/agents
```

The same key can also be used with the PromptRails SDKs and CLI for authenticating requests.

## Managing Keys

List, review, rotate, and delete API keys from **Settings > API Keys** in the dashboard.

## Key Rotation Best Practices

- **Rotate keys regularly** -- Create a new key, update your applications, then delete the old key
- **Use expiration dates** -- Set keys to expire and create replacement keys before expiration
- **Minimize scopes** -- Grant only the permissions each integration needs
- **Use separate keys per environment** -- Different keys for development, staging, and production
- **Monitor usage** -- Check `last_used_at` to identify unused keys
- **Never share keys** -- Each integration should have its own key
- **Store securely** -- Keep keys in environment variables or secret managers, never in source code

## Key Response Fields

| Field             | Type      | Description                         |
| ----------------- | --------- | ----------------------------------- |
| `id`              | KSUID     | Unique key identifier               |
| `workspace_id`    | KSUID     | Workspace scope                     |
| `name`            | string    | Display name                        |
| `key_prefix`      | string    | First characters for identification |
| `scopes`          | array     | Granted permission scopes           |
| `allowed_ips`     | array     | IP allowlist                        |
| `allowed_origins` | array     | CORS origin allowlist               |
| `last_used_at`    | timestamp | Last usage time                     |
| `expires_at`      | timestamp | Expiration time                     |
| `created_at`      | timestamp | Creation time                       |

## Related Topics

- [Security](/docs/security) -- Overall security architecture
- [REST API Reference](/docs/rest-api-reference) -- API authentication details
- [Team and Roles](/docs/team-and-roles) -- User vs API key authentication