API Keys and Scopes

Create API keys that give each service, script, widget, or integration only the access it actually needs.

API keys authenticate programmatic access to PromptRails. Create separate keys for local development, backend services, CI jobs, MCP clients, public widgets, and trace ingestion so each integration has only the permissions it needs.

PromptRails API Keys settings showing key list and access controls — API keys live in workspace settings. Use this page to create scoped keys, review existing keys, and keep programmatic access separate by environment or integration.

Creating API Keys

Create an API key from the PromptRails dashboard:

Open Settings > API Keys.
Select Create API Key.
Enter a name and choose the minimum required scopes.
Optionally add IP restrictions, allowed origins, and an expiration date.
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.

Technical detailsScope reference

Scopes

Scopes control what operations an API key can perform. Choose the minimum set needed for the integration.

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
`traces:write`	Ingest external trace spans (SDK/OTLP)

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

Agent Trigger Scopes

Scope	Description
`agent_triggers:read`	List and view agent triggers (generic webhook, Slack, Telegram, Teams, WhatsApp, schedule)
`agent_triggers:write`	Create, update, and delete agent 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.

Technical detailsKey format and response fields

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:

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

Security -- Overall security architecture
REST API Reference -- API authentication details
Team and Roles -- User vs API key authentication