Authentication

API Keys

All Rapidfolio API requests are authenticated with an API key passed in the Authorization header:

Authorization: Bearer <your-api-key>

Keys are created in the Rapidfolio dashboard under Settings → API Keys. The raw key value is shown exactly once at creation — store it securely in a secret manager or environment variable immediately. Rapidfolio does not display the key again after you close the creation dialog.

---

Key Prefixes

The prefix of a key indicates its type and environment:

Prefix	Type	Environment
rsk_sandbox_	Runner (API) key	Sandbox
rsk_live_	Runner (API) key	Live

You can always identify which environment a key belongs to from its prefix, even without checking the dashboard.

---

Environments

Rapidfolio has two fully isolated execution environments. You specify the environment in two places that must agree with each other:

1. The URL path — include sandbox or live as the last segment when running a procedure (e.g. /v1/procedures/:id/sandbox).
2. The API key prefix — rsk_sandbox_ keys can only be used against sandbox URLs; rsk_live_ keys against live URLs. Rapidfolio rejects requests where the key environment and URL path disagree.

Environment	URL path segment	Key prefix
Sandbox	/sandbox	rsk_sandbox_
Live	/live	rsk_live_

Both environments share the same base URLs:

• Runner API: https://run.rapidfolio.com
• Dashboard API: https://app.rapid.io/api/v1

Note: Connections (Stripe accounts, Plaid credentials, etc.) are also scoped to an environment. A sandbox key will only invoke sandbox connections, and vice versa. Make sure you have configured connections for the environment you are targeting.

---

Example Request

curl -X POST https://run.rapidfolio.com/v1/procedures/PROCEDURE_ID/sandbox \
  -H "Authorization: Bearer rsk_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"data": {"customerId": "cust_123"}}'

---

Error Responses

Status	Meaning
401 Unauthorized	The Authorization header is missing, malformed, or the key does not exist
403 Forbidden	The key is valid but does not have permission to perform the requested action
429 Too Many Requests	The key has exceeded its rate limit — back off and retry

401 Response body

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

403 Response body

{
  "error": "Forbidden",
  "message": "This API key does not have access to the requested resource"
}

429 Response body

{
  "error": "TooManyRequests",
  "message": "Rate limit exceeded. Retry after 30 seconds.",
  "retryAfter": 30
}

Respect the retryAfter value in seconds when you encounter a 429. Retrying immediately will continue to fail.

---

Security Best Practices

• Store API keys in environment variables or a secrets manager — never hard-code them in source code.
• Use sandbox keys during development and CI. Live keys should only be present in production environments.
• Rotate keys immediately if you suspect they have been compromised — delete the old key from Settings → API Keys and create a new one.
• Avoid logging request headers that contain Authorization values.