Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.have-foresight.app/llms.txt

Use this file to discover all available pages before exploring further.

The Foresight RCM API uses API key authentication. Every request must carry a valid key in either the X-API-Key header (preferred) or the standard Authorization: Bearer header.

​
Generating a key

Generate keys in the dashboard at Settings → API keys. Each key:
  • Is scoped to a single organization. Keys cannot cross organization boundaries.
  • Has an explicit set of scopes (least-privilege; see Scopes).
  • Is shown once at creation and is never retrievable again. Store it in a secrets manager.
  • Can be rotated, disabled, or revoked at any time without notice to callers.
API keys begin with fsk_ followed by a 64-character random body. The prefix is non-secret and safe to include in logs.

​
Sending the key

The canonical header is X-API-Key. The standard Authorization: Bearer header is also accepted for compatibility with HTTP libraries that don’t expose custom headers easily. 
curl https://api.have-foresight.app/v1/patients \
  -H "X-API-Key: fsk_live_..."
If both headers are present, X-API-Key wins.

​
Test vs live keys

Live and test keys are completely separated.
PrefixEnvironmentTalks to real payers?Triggers webhooks?
fsk_live_...ProductionYesYes (live URLs)
fsk_test_...SandboxNo (mocked)Yes (sandbox URLs)
Use test keys against https://api.staging.have-foresight.app/v1 for end-to-end testing without touching real PHI or submitting real claims.

​
Scopes

API keys carry an explicit list of scopes. The API rejects any request whose scope is not present on the key with 403 forbidden_scope. Common scopes:
ScopeGrants access to
patients:readList, retrieve patients
patients:writeCreate, update patients
eligibility:readRetrieve eligibility / benefits responses
eligibility:writeTrigger new eligibility checks
prior_auth:readList / retrieve PAs and questions
prior_auth:writeSubmit PAs, answer questions
claims:readList, retrieve claims
claims:writeCreate, validate, scrub, submit claims
denials:readList, retrieve denials
appeals:writeGenerate, send appeals
webhooks:writeManage webhook subscriptions
The dashboard shows the full scope catalog, including read-only and admin-only variants. Always grant the smallest set of scopes a key needs.

​
Rotating keys

To rotate without downtime:
  1. Create a new key with the same scopes.
  2. Deploy your applications with the new key.
  3. After confirming the old key is no longer in use (check the Last used timestamp in the dashboard), revoke it.
The old and new keys are both valid until the old one is explicitly revoked.

​
Idempotency

Mutation endpoints (POST, PUT, PATCH) accept an Idempotency-Key header. See Idempotency for the full contract.

​
Common authentication errors

StatusCodeMeaning
401missing_api_keyNo X-API-Key or Authorization header sent.
401invalid_api_keyKey was malformed, revoked, or doesn’t exist.
401expired_api_keyKey passed its expiration date.
403forbidden_scopeKey is valid but missing the scope this call needs.
403organization_mismatchResource belongs to a different organization.
See Errors for the full error envelope.

​
Web app sessions (browser)

When a request comes from the Foresight dashboard rather than a server-side integration, the API also accepts an authenticated user session via Clerk. This path is for first-party UI only — third-party integrations should always use API keys.