Overview
PCX supports two credential types — API keys for server-to-server integrations and JWTs for user-facing flows. Both use the same underlying mechanism: PCX’s API Gateway runs a custom Lambda Authorizer that inspects two headers on every request.
Both headers must always be present. Whichever header is not being used for authentication must be sent with the literal string value NONE. The authorizer ignores headers with the value NONE — it does not treat them as credentials.
| Header | API key flow | JWT flow |
|---|
Authorization | NONE (literal string) | Bearer <cognito_jwt> |
X-Api-Key | <your_api_key> | NONE (literal string) |
Sending only one header, or omitting the unused header entirely, will result in a 401 Unauthorized response.
API key authentication (server-to-server)
Use this for backend integrations and automated workflows. Send your API key in X-Api-Key and set Authorization to the literal string NONE.
curl https://prod-api.pcxpay.com/v1/organizations/{org_id} \
-H "X-Api-Key: your_api_key_here" \
-H "Authorization: NONE"
Never expose API keys in client-side code or public repositories. Rotate immediately if compromised.
JWT authentication (user-facing flows)
Use this when an end user has authenticated through Cognito. Send the JWT as a Bearer token in Authorization and set X-Api-Key to the literal string NONE.
curl https://prod-api.pcxpay.com/v1/transactions \
-H "Authorization: Bearer eyJraWQ..." \
-H "X-Api-Key: NONE"
PCX’s API Gateway uses a custom Lambda Authorizer of type REQUEST. Unlike a Cognito authorizer — which only inspects the Authorization header — a REQUEST authorizer receives the full set of request headers and decides which credential to validate based on what it finds.
Sending only one header causes the authorizer to reject the request with 401 because it cannot determine whether the missing header was intentionally omitted or accidentally dropped. The NONE value is a deliberate signal: it tells the authorizer the header is present but unused, allowing it to route cleanly to the correct validation path.
API playground note
Mintlify’s API playground sends X-Api-Key as the auth header. When testing JWT flows in the playground, manually add both headers — set Authorization to Bearer <your_jwt> and X-Api-Key to NONE.
Errors
| Status | Meaning |
|---|
401 | Missing, invalid, or incomplete headers |
403 | Valid credentials but insufficient permissions |
{
"status": "error",
"message": "Unauthorized"
}
