CentraPoint

Getting started

Authentication

Authenticate API requests with a tenant-scoped Bearer API key; plan and account requirements.

On this page

Bearer API keys#

Every request to /api/v1/… must include an API key in the Authorization header using the Bearer scheme:

HTTP
GET /api/v1/transactions/CP-20260925-9F3A1C7B HTTP/1.1
Host: app.centrapoint.co.za
Authorization: Bearer cp_1a2b3c4d_your-secret-here

Requests without a key, with a different scheme (for example Basic), or with a key that does not start with cp_ are rejected with 401 unauthorized and the message Missing or malformed API key. Unknown or revoked keys receive 401 unauthorized with Invalid API key.

Key format#

Keys have three parts separated by underscores: cp_, an 8-character hexadecimal key ID, and a random secret.

Format
cp_<8 hex characters>_<secret>

cp_1a2b3c4d_Q2VudHJhUG9pbnQtZXhhbXBsZS1vbmx5
  • The prefix (cp_1a2b3c4d) identifies the key and is shown in the dashboard.
  • CentraPoint stores only a SHA-256 hash of the full key and compares it in constant time. Nobody, including CentraPoint support, can show you an existing key again. If you lose it, create a new one.
  • Treat the whole string as opaque. Do not split, trim or re-encode it.

Organisation scope#

Each key belongs to one organisation (tenant). Everything the key creates belongs to that organisation, and lookups only see that organisation's data: a transaction reference from another organisation returns 404 not_found. If you operate several organisations, create a key in each.

Plan requirements#

API access is a plan feature. It is included on Growth and higher plans. Plans also limit how many active API keys you can create. See your plan under Settings → Billing in the dashboard or centrapoint.co.za for current plans.

Plan-related responses
SituationStatuserrorApplies to
Your plan does not include the REST API403plan_restrictedAll endpoints
Your plan does not include payment links403plan_restrictedPOST /api/v1/payment-links
A plan quota is reached (e.g. customers)403plan_limitPOST /api/v1/payment-links

Read-only accounts#

If an organisation is suspended, cancelled, or its free trial has ended, it becomes read-only. Requests that create data (such as POST /api/v1/payment-links) return 403 account_restricted with an explanatory message. Read requests such as transaction lookups keep working, so you can still reconcile outstanding payments. Existing payment links stop accepting payments while the account is read-only.

Per-key rate limits#

Rate limits apply per API key: 120 requests per minute each, shared across all CentraPoint servers. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Using a separate key per system gives each its own budget. See Rate limits.

Creating, rotating and revoking keys#

  • Only organisation administrators can manage keys, under Settings → API keys.
  • Create one key per system and environment (for example Website – production, Website – staging), so you can revoke one without affecting the others and each has its own rate-limit budget.
  • Rotate by creating a new key, deploying it, confirming traffic uses it (the dashboard shows each key's Last used time) and then revoking the old key.
  • Revoke takes effect immediately: requests with a revoked key return 401.

Security best practice#