Skip to main content

​
Overview

The Public Service is PCX’s externally-facing integration layer. Unlike all other PCX services — which use Bearer JWT tokens issued through the user auth flow — the Public API authenticates using API keys passed in the X-API-Key request header. This makes it suitable for server-to-server integrations where a persistent credential is needed without a user login flow. When a valid API key is presented, the service resolves the caller’s organisation (org_id) and user (user_id) automatically. These identities are then used to scope all operations without requiring them to be repeated in every request body.

​
Authentication

Every request must include the API key in the X-API-Key header: 
X-API-Key: pcx_abc123_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If the header is absent or the key is invalid, the service returns 401 with { "message": "API Key is missing", "status": "error" }. API keys are created and managed through the API Keys endpoints below.

​
API Keys

API keys are the primary credential for the Public API. Each key is scoped to an org_id and a user_id and can be independently activated, revoked, or deleted.

​
Key lifecycle

  1. Create — POST /public/api-keys/create. The response includes the full key value exactly once. Store it immediately; it cannot be retrieved afterwards.
  2. List — GET /public/api-keys?org_id=<id>. Returns paginated key metadata (prefix, name, status, timestamps). The secret value is never returned.
  3. Revoke — PATCH /public/api-keys/{prefix}/revoke. Disables the key without deleting the record. Useful when a key may have been exposed — it preserves the audit trail while immediately cutting off access.
  4. Delete — DELETE /public/api-keys/{prefix}. Permanently removes the key. Use when a key is no longer needed and the record is not required for compliance purposes.

​
Key identification

Keys are identified in two ways:
IdentifierUsed for
api_key_idFetching key metadata via GET /public/api-keys/{api_key_id}
prefixRevoking or deleting via the {prefix} path parameter
The prefix is a short, non-secret substring of the key (e.g. pcx_abc123) that uniquely identifies it without exposing the full secret.

​
Webhooks

Webhooks let you receive real-time transaction events at your own endpoint. The flow is:
  1. Register — POST /public/webhooks. Provide an endpoint_url (must be HTTPS and publicly reachable). The org is inferred from your API key — no org_id needed.
  2. Receive — PCX dispatches a POST to your endpoint whenever a transaction update occurs. Your endpoint should return 2xx to acknowledge receipt.
  3. Notify — POST /public/webhooks/notify. Programmatically push a transaction_data payload to all registered webhook endpoints for a given org_id. This is useful for manually triggering notifications during testing or replaying missed events.

​
Webhook payload

The transaction_data field in the notify request is a free-form object. A typical payload looks like: 
{
  "transaction_id": "txn_abc123",
  "status": "completed",
  "amount": 500.00,
  "currency": "USD",
  "updated_at": "2024-01-15T10:30:00Z"
}
Your webhook receiver should be idempotent — the same event may be delivered more than once under failure/retry scenarios.

​
Pagination

List endpoints (e.g. GET /public/api-keys) use DynamoDB cursor pagination. Pass last_evaluated_key from meta.last_evaluated_key in the previous response to fetch the next page. When the value is null, you have reached the last page.