An API key is a server integration credential with enforced scopes. Authentication checks its hash, active status, expiration and rate limits, then creates a transient system identity for the organization. It does not load the key creator as the caller.
Video tutorials for this topic
Using a key
x-api-key: <key>
orgid: acmeapiKey is accepted as well. Keep sending the key on scoped integration requests: the middleware evaluates each request's method, path and datatype before injecting a bearer for downstream authentication. A returned bearer from /api-key/auth is not a promise of a portable scoped person session.
Scope rules
Supported areas are profile, users, billing, analytics, admin and data. Use explicit scopes such as read:data or write:users. write:<area> includes reads in that area. Empty or nonmatching scopes are denied with 403 and code: "api_key_scope". Bare read/write and wildcard forms grant broader access; choose a narrower area when possible.
| Request | Required key scope |
|---|---|
POST /repository/find/sf_product with {query, options} | read:data |
POST /repository/find/user | read:users |
POST /repository/create with datatype: "sf_product" | write:data |
GET /repository/collections | read:admin |
POST /repository/file/flatlist or /file/signurl | write:admin |
POST /repository/file/upload | write:admin |
The action classifier treats repository find/query/search/aggregate POSTs as reads. File POSTs are classified as writes even when the handler only reads a file. A matching scope is necessary but does not bypass content permissions, staff-only restrictions or business guards. In particular, a System identity still needs a person token for the repository write paths that enforce customer delegation.
Create a restricted read key through an authorized staff session:
/api-key/createThe response's top-level apiKey is the one-time secret. Retain the record's sk separately for management. The secret is hashed in storage; listing keys does not recover it.
Managing keys
/api-key/createJWT/api-key/listJWT/api-key/:keyIdJWT/api-key/:keyIdJWT/api-key/:keyIdJWT/api-key/regenerate/:keyIdJWT/api-key/usage/:keyIdJWTKeys are apikey records. regenerate issues a new secret against the same key record, so you can rotate without re-pointing whatever references it.
Administration
/api-key/admin/listJWT/api-key/admin/revoke/:keyIdJWTBoth require RootAdmin or ConfigAdmin.
Org users
/api-key/org/:orgidJWT/api-key/org/:orgid/createJWT/api-key/org/:orgid/deleteJWTCreate and delete require RootSystem, RootAdmin or RootPowerUser. These manage organization API-key records. The read route also requires one of these root roles.
Direct authentication
/api-key/authNo authThe handler takes x-api-key and returns { user, apiKey: { id, name, scopes }, token }. With a key header present, middleware scope checks still run before this public handler; this path is classified as write:admin. Prefer sending the key on the actual integration request instead of exchanging it to evade its scope checks.
Blocking a key
/profile/blacklist/apikey/addJWT/profile/blacklist/apikey/delete/:apiKeyJWTBlacklistMiddleware rejects blocklisted keys before the request reaches a controller — the fast path for cutting off a leaked key without waiting for a rotation to propagate.
Scope checks do not make a key an interactive staff login. Use the staff session APIs for operator sessions and the app-plus-person flow for client applications.

