API Keys And Origins
Application identity is the front door to hosted SPAPS. Send the provisioned key in X-API-Key.
Publishable browser keys also require an exact allowed origin; secret keys belong only in server-side
secret storage. A secret key does not replace user-session, role, or capability checks on
protected routes.
Key Types
| Type | Prefix | Intended caller | Main constraint |
|---|---|---|---|
| Publishable | spaps_pub_ | Browser app | Endpoint scope and Origin validation |
| Secret | spaps_sec_ | Server process | Keep out of browsers, repositories, and logs |
Origin Check Flow
Configure Browser Origins
Add origins through the hosted application settings. Include the exact scheme, host, and port. For
example, https://app.example.com and http://localhost:3000 are different origins. The local URL
is your frontend; SPAPS remains hosted.
Origin Validation Checklist
| Check | Command or inspection | Expected signal | If it fails |
|---|---|---|---|
| Hosted API is reachable | curl -fsS https://api.sweetpotato.dev/health | Health response returns successfully | Start with Troubleshooting |
| Staging credentials are intentional | Inspect the provisioned application and key prefix | Application and key type match the staging plan | Replace copied or production credentials |
| Browser origin is allowlisted | Inspect the hosted application settings | The exact scheme, host, and port are present | Update the application setting, not frontend config only |
| Webhook and secret traffic use server keys | Review caller location and key prefix | Browser uses spaps_pub_; servers keep secret keys off the client | Rotate exposed secret keys and move calls server-side |
Common Mistakes
Apply an origin to the correct hosted staging or production application. Treat the environments as separate configuration; never copy production secrets into staging to bypass an origin error.
- Putting the user JWT in
X-API-Key. Send the application key there and the user token inAuthorization: Bearer <token>. - Adding an origin only to frontend config instead of the hosted application settings.
- Using a publishable key on an endpoint that requires a secret key.