API keys

API keys (fm_ + 48 hex characters) authenticate every FaceMode REST call. Keys are scoped, optionally expiring credentials owned by your account - at most 5 may exist at once (API_KEY_LIMIT_REACHED).

The raw key is returned exactly once by POST /api/keys inside apiKey.key. Store it immediately. List and get responses only ever show the masked prefix (for example fm_ab12cd****).

Endpoints

Method	Path	Scope	Description
GET	`/api/keys`	`keys:read`	List keys
POST	`/api/keys`	`keys:write`	Create a key
GET	`/api/keys/{id}`	`keys:read`	Get a key
PATCH	`/api/keys/{id}`	`keys:write`	Update a key
PATCH	`/api/keys/{id}/revoke`	`keys:write`	Revoke a key
DELETE	`/api/keys/{id}`	`keys:delete`	Delete a key

Scopes

Keys default to sessions:create, sessions:read, sessions:end, avatars:read, and usage:read. Pass scopes at creation to customize; valid values are: sessions:create, sessions:read, sessions:end, avatars:read, avatars:write, keys:read, keys:write, keys:delete, billing:read, billing:write, credits:read, usage:read Unknown scope names fail with INVALID_SCOPES. See the scopes table for which scope gates which endpoint.

Revoke vs delete

Revoking sets is_active: false - the key is rejected immediately but its record stays visible for audit. Deleting removes the record entirely. Both are permanent for the raw key: there is no un-revoke.

API Reference

Sessions

Avatars

API keys

Endpoints

Scopes

Revoke vs delete

​Endpoints

​Scopes

​Revoke vs delete

Endpoints

Scopes

Revoke vs delete