Authentication and scopes

Every request carries one organization API key as a bearer token. There is no OAuth flow, no refresh token, and no per-user identity.

Sending the key

Put the key in the Authorization header. Any other placement, including a query parameter, is rejected.

curl -sS "https://app.enrollpilot.com/api/v1/provider-groups" \
  -H "Authorization: Bearer epk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

A missing, malformed, unknown, revoked, or expired key all return the same response. The API deliberately never tells a caller which of those it was.

{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or missing API key."
  }
}

Key format

Keys start with epk_live_ followed by 40 letters and digits.
The full key is displayed exactly once, in the dialog that creates it. EnrollPilot stores only a SHA-256 hash and cannot show or recover the original.
The console lists each key by its first 12 characters, which is not enough to reconstruct it.

If you lose a key

Create a replacement, move your integration onto it, then revoke the old one. There is no recovery path, and that is the point.

Scopes

A key only reaches what its scopes allow. Calling an endpoint outside a key's scopes returns 403 insufficient_scope. Grant the narrowest set that does the job.

Scope	Grants	Requires
`providers:read`	Read provider roster, contact details, and identifiers	None
`providers:read:sensitive`	Additionally read date of birth and demographic fields	`providers:read`
`groups:read`	Read provider groups, locations, and group identifiers	None
`enrollments:read`	Read provider enrollment cases and group contracts	None
`documents:read`	Read document metadata (no file contents)	None

Sensitive provider fields

Date of birth, gender, ethnicity, ethnicity detail, birth city and birth country are returned only when the key holds providers:read:sensitive. Without that scope those keys are absent from the payload entirely rather than present and null.

Never returned, at any scope

Social Security numbers, payer portal credentials, and free-text notes of any kind are excluded from every response by construction. No scope unlocks them and none ever will in version 1.

Key lifecycle

Any organization admin can create keys. An organization can hold up to 10 active keys at once.
A key can be given an optional expiry date at creation. After it passes, the key stops working and cannot be reactivated.
Revoking a key takes effect on the very next request. Revocation is permanent.
Key creation and revocation are recorded in your organization's audit log. Individual API requests are not audit logged; per-key daily request and error counts are shown on the API keys page instead.

Rotation

Rotate on a schedule and whenever someone with access leaves. Because keys are independent, rotation is a clean overlap: create the new key, deploy it, confirm traffic on the new key in the usage table, then revoke the old one. No request is dropped in between.

Billing and availability

Keys are identity, not entitlement. If your subscription lapses, the keys stay in place and start returning 402. Once billing is resolved, the same keys resume working with no reissue and no code change. See 402 handling on the errors page.