API Authentication

Create and manage Integration API keys with scopes, IP allowlists, and rate limits.

Integration API requests authenticate with API keys — long-lived Bearer tokens scoped to your workspace.

Creating an API key

Open your workspace Integrations page.
Click Create API key.
Configure name, scopes, and optional restrictions.
Copy the full secret immediately — it is shown only once at creation.

Key format

ra_live_<prefix>_<secret>

Example:

ra_live_a1b2c3d4e5f6_7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f3

Send the full string as a Bearer token:

curl -H "Authorization: Bearer ra_live_..." \
  https://your-app.example.com/api/v1/integrations/agents

Key controls

Setting	Purpose
Name	Label for identification in the UI
Scopes	Permission boundaries for the key
Allowed task IDs	Restrict which tasks can be executed (null = all)
Allowed agent IDs	Restrict which agents can be used (null = all)
IP allowlist (CIDR)	Only accept requests from listed IP ranges
Rate limit	Requests per minute (default 60)
Max concurrent executions	Cap simultaneous runs triggered by this key
Expires at	Optional expiration datetime

Scoping best practices

Create separate keys per integration or environment (production vs. staging).
Restrict allowed_task_ids and allowed_agent_ids to the minimum required.
Set IP allowlists when your integration runs from fixed infrastructure.
Use short expiry for temporary integrations; rotate keys periodically.

Revocation

Revoke a key from the Integrations page. Revoked keys immediately fail authentication with unauthorized. Update your integration with a new key before revoking the old one.

Rate limiting

When rate limit is exceeded, the API returns 429 with error code rate_limited. Default limit is 60 requests per minute per key. Configure per-key limits in the Integrations UI.

Security notes

Store secrets in environment variables or a secrets manager — never commit them to source control.
The secret is hashed (bcrypt) server-side; reArray cannot recover a lost secret. Create a new key if lost.
API keys are workspace-scoped — they cannot access other workspaces' data.
Platform vault credentials ($secrets.*) are separate from API keys and never exposed via the Integration API.