Authentication
Create an organization-scoped API key and authenticate your server requests.
Authenticate with an API key
Server integrations use an organization-scoped key in the standard authorization header. Create a key in Settings → Developer using a signed-in session with API-key administration permission.
Authorization: Bearer <YOUR_FACILY_API_KEY>Use an environment-specific key. The local, stg, and live token segments identify the environment. The full value is returned once on creation; later reads return a display hint.
Permissions and facility scope
A key has its own explicit permissions, capped by the creating user’s permissions at creation and by the editing user’s permissions when edited. It can be organization-wide or restricted to selected facilities. An optional CIDR allowlist restricts the source IP.
A valid key without sufficient scope or permission returns 403. Repeatedly retrying the same credential does not grant access.
Signed-in sessions
Staff sessions use Facily-issued JWTs. Auth0 remains an identity provider behind the sign-in flow, but an arbitrary Auth0-issued token is not a substitute for the Facily session token.
Session authentication also uses Authorization: Bearer <ACCESS_TOKEN>. Use the documented sign-in flow in the Facily dashboard for the supported sign-in and refresh flow. This portal does not provide a generic OAuth client-credentials registration service.
Partner integrations
Partner keys are associated with a lead channel. They authenticate the Partner API, with channel and facility constraints. An ordinary staff key or session is not interchangeable with a partner key.
Partner calls run on your server. Confirm channel setup, key type, facility access, and production eligibility with your Facily administrator.
Keep credentials manageable
- Use a separate named key for each integration and environment.
- Grant only the operations and facilities the integration needs.
- Store secrets in your deployment’s secret manager.
- Replace a lost key; its secret cannot be recovered.
- Revoke unused or exposed keys from a signed-in administrative session.