API Keys & Scope Isolation

Understanding key prefixes, permission scopes, and lifecycle management.

API Keys & Scope Isolation

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

🔑 Key Prefix Reference & Scoping

Prefix	Scope	Purpose	Storage & Billing
`sp_live_...`	`api_sdk`	Production SDK integrations	Deducts from monthly plan quota; saves assets to Edge CDN
`sp_test_...`	`api_sdk`	Logical Sandbox testing	Zero quota deduction; 24-hour ephemeral auto-expire storage
`sp_sdk_...`	`api_sdk`	Standard Developer SDKs	Standard SDK access scope
`sp_wp_...`	`wordpress`	WordPress Plugin	Scoped strictly to WordPress Media Library integrations

🛡️ Scope Enforcement & Double Verification

SmallPict enforces double validation on every API call:

Prefix Check: The API Gateway validates that the key string matches the intended prefix format.
Database Record Scope: The backend checks the stored scope in PostgreSQL (api_sdk vs wordpress).

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

🔄 API Key Lifecycle Management

Key Creation

Generate new API keys directly from your SmallPict customer dashboard under the API Keys section. You can name your keys (e.g. Production E-commerce API, Staging Testing Key) for clear audit logs.

Key Rotation

To rotate an API key with zero downtime:

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

Key Revocation

Revoked keys immediately return HTTP 403 Forbidden (API_KEY_REVOKED).