docs
/
AppEngine API

API keys

Long-lived credentials for server-to-server access, and how they resolve to a user.

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.

Using a key

x-api-key: <key>
orgid: acme

apiKey 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.

RequestRequired key scope
POST /repository/find/sf_product with {query, options}read:data
POST /repository/find/userread:users
POST /repository/create with datatype: "sf_product"write:data
GET /repository/collectionsread:admin
POST /repository/file/flatlist or /file/signurlwrite:admin
POST /repository/file/uploadwrite: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:

POST/api-key/create

The 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

POST/api-key/createJWT
GET/api-key/listJWT
GET/api-key/:keyIdJWT
PUT/api-key/:keyIdJWT
DELETE/api-key/:keyIdJWT
POST/api-key/regenerate/:keyIdJWT
GET/api-key/usage/:keyIdJWT

Keys are apikey records. regenerate issues a new secret against the same key record, so you can rotate without re-pointing whatever references it.

Administration

GET/api-key/admin/listJWT
POST/api-key/admin/revoke/:keyIdJWT

Both require RootAdmin or ConfigAdmin.

Org users

GET/api-key/org/:orgidJWT
POST/api-key/org/:orgid/createJWT
POST/api-key/org/:orgid/deleteJWT

Create 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

POST/api-key/authNo auth

The 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

POST/profile/blacklist/apikey/addJWT
DELETE/profile/blacklist/apikey/delete/:apiKeyJWT

BlacklistMiddleware 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.