Pengine Store API
Guides

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-Key header 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:

401 Unauthorized
{ "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:

401 Unauthorized
{ "error": { "statusCode": 401, "code": "api_key_invalid", "message": "Invalid API key" } }

If the key matches but the store is inactive:

401 Unauthorized
{ "error": { "statusCode": 401, "code": "store_inactive", "message": "The store is not active" } }

If the key matches but the API is disabled for the store:

401 Unauthorized
{ "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.

On this page