API Keys & Scope Isolation

Understanding key prefixes, permission scopes, and lifecycle management.

SmallPict uses structured key prefixes to isolate access permissions, rate limits, and billing quotas across different integration types.

Key prefixes and scopes

Prefix	Scope	Purpose	Storage & Billing
`sp_sdk_...`	`api_sdk`	Production SDK integrations	Counts against your monthly quota; storage and delivery depend on your plan (Platform Overview)
`sp_test_...`	`api_sdk`	Sandbox testing	No quota usage; files are deleted after 24 hours
`sp_wp_...`	`wordpress`	WordPress Plugin	Scoped strictly to WordPress Media Library integrations

How scopes are enforced

Every API call is checked twice:

Prefix Check: The API Gateway validates that the key string matches the intended prefix format (sp_wp_ for WordPress, sp_sdk_ or sp_test_ for API/SDK).
Database Record Scope: SmallPict checks the scope stored for the key (api_sdk vs wordpress).

Warning: Attempting to call WordPress plugin endpoints (/v1/plugin/*) with an SDK key (sp_sdk_...), or vice versa, will result in an HTTP 403 Forbidden (ERR_KEY_SCOPE_MISMATCH).

Managing keys

Creating keys

Generate new API keys directly from your SmallPict customer dashboard under the API Keys section. Give each key a name (for example Production E-commerce API or Staging Testing Key) so it is easy to identify in audit logs.

Rotating keys

To rotate a key without downtime:

Generate a new key pair in your dashboard.
Update your application's environment variables (SMALLPICT_API_KEY and SMALLPICT_SECRET_KEY).
Deploy and confirm in the dashboard that requests use the new key.
Revoke the old key from the dashboard.

Revoking keys

Revoked keys immediately return HTTP 403 Forbidden (API_KEY_REVOKED).