Authentication
How API keys work, where to get them and how to use them.
Each custom store has one API key. You need the key and the store ID to authenticate requests.
Get your credentials
Open your custom store in the Pengine app and enable the Store API. Copy the store ID and API key, then store them as secrets in your application environment.
This video shows each step in the app, from creating the custom store to sending a first request. Watch on YouTube.
export PENGINE_STORE_ID="ovy3u54frpsl4sd963aja0h1"
export PENGINE_API_KEY="pgn_qfL0dZrwqXYuwvlt4nYlB0ytL78Uv4PU"Current keys begin with pgn_ and contain 36 characters. Treat the value as opaque and do not
validate or parse its format in your application.
Authenticate a request
Send the API key in the X-API-Key header with every request. Include the matching store ID in the
request path.
curl https://api.pengine.io/store-api/2026-08/stores/$PENGINE_STORE_ID/status \
-H "X-API-Key: $PENGINE_API_KEY"The Store API does not use OAuth, token exchanges, or expiring credentials.
The key and the store must match
An API key grants access only to the custom store that issued it. If you manage several stores, keep each store ID with its corresponding key and select the pair for each request.
The API returns 401 when the key does not match the store ID in the path. Resources are also scoped
to that store: a resource ID from another store returns 404, just like an ID that does not exist.
Protect the key
The key can access every Store API resource, upload artwork, and create orders billed to your store. Store API keys do not support scopes or read-only access.
Server-side only
Make Store API requests from your backend. Never expose the key in browser JavaScript, a mobile app, a public repository, or any response sent to a client.
- Load the key from an environment variable or secret manager.
- Redact the
X-API-Keyheader from application logs, request dumps, and error reports. - Use a separate custom store and key for each environment so staging cannot create production orders.
Handle authentication failures
Authentication failures return 401 with a code that identifies the cause.
If the X-API-Key header is missing:
{ "error": { "statusCode": 401, "code": "api_key_missing", "message": "The API key is missing" } }If the key is invalid, belongs to another store, or names a store that does not exist:
{ "error": { "statusCode": 401, "code": "api_key_invalid", "message": "Invalid API key" } }If the key matches but the store is inactive:
{ "error": { "statusCode": 401, "code": "store_inactive", "message": "The store is not active" } }If the key matches but the API is disabled for the store:
{ "error": { "statusCode": 401, "code": "api_disabled", "message": "The API is disabled for this store" } }Disabling the API in the Pengine app keeps the key. When you enable the API again, the same key works.
Do not retry a 401 automatically. Check that your HTTP client sends the header, the key and store ID
match, the deployed key is current, the store is active, and the API is enabled.
Rotate the key
Rotate the key from your custom store's API settings in the Pengine app. You can keep the old key working for up to 72 hours, so you can deploy the new key without downtime. With no overlap, the old key stops working immediately.
Rotation also changes your webhook signature
Pengine signs webhook requests with the same API key. During an overlap, each delivery carries a signature for both keys, so a receiver that still has the old key keeps working. See Verifying signatures.
Prepare the rollout
Identify every service that sends Store API requests or verifies webhook signatures. Choose an overlap long enough to update all of them.
Rotate and store the key
Rotate the key in the Pengine app, then replace the old key in your application's environment or
secret storage. The old key returns 401 when the overlap ends, or immediately if you chose none.
Deploy and verify
Deploy the updated secret to your API clients and webhook receivers. Then call
GET /status. A 200 confirms that the new key matches the store.
Respond to a leaked key
Rotate the key immediately, with no overlap, so the leaked key stops working at once. A leaked key can access your store's resources and create orders billed to your store.
After rotation, review the API request log and order list in the Pengine app. The request log retains 14 days of methods, paths, status codes, and durations. Investigate unexpected requests or orders.