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:
GET /api/v1/transactions/CP-20260925-9F3A1C7B HTTP/1.1
Host: app.centrapoint.co.za
Authorization: Bearer cp_1a2b3c4d_your-secret-hereRequests 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.
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.
| Situation | Status | error | Applies to |
|---|---|---|---|
| Your plan does not include the REST API | 403 | plan_restricted | All endpoints |
| Your plan does not include payment links | 403 | plan_restricted | POST /api/v1/payment-links |
| A plan quota is reached (e.g. customers) | 403 | plan_limit | POST /api/v1/payment-links |
Some endpoints also need a specific plan feature on top of the REST API:
| Endpoints | Plan feature |
|---|---|
/api/v1/invoices/… | Invoicing (creating an invoice pay link also needs Payment links) |
/api/v1/payment-links, /api/v1/eft-orders/… | Payment links |
/api/v1/packages/…, /api/v1/plans/…, /api/v1/customer-subscriptions/… | Recurring billing |
/api/v1/mandates/… | Debit orders |
/api/v1/coupons/… | Coupons |
/api/v1/reconciliation/… | Reconciliation |
POST /api/v1/customers/{id}/portal-link | Customer portal (returns 409 portal_disabled when off) |
GET /api/v1/entitlements/{key} | None: any valid API key, even without the REST API |
Read-only accounts#
If an organisation is suspended or cancelled, or its CentraPoint account is limited to billing (a plan payment still unpaid 3 days after it fell due, or no card on a paid plan after the grace period), or the free trial of a plan sold through sales (no online price) 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. 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#
- Users with the Create and revoke API keys permission (
api_keys:write, administrators by default) 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.
Key permissions. Every key can call the API described in these docs, except charging a customer's saved card without the customer present (charge a saved card). An administrator allows that per key with Allow in the Charge saved cards column under Settings → API keys; without it the endpoint answers 403 permission_required. The same permission decides whether customers can pay with a saved card on a payment link, invoice link or portal sign-in link the key made (see links made with the API). Allow it only on the key your billing system uses. GET /api/v1/me lists the calling key's permissions in apiKey.permissions.
Security best practice#
Request logging and audit logs#
Every request to the API is logged, successful or not (including 401, 403, 404, 409, 422, 429 and 5xx responses), with the method, path, response status, error code, duration, the key's public prefix (for example cp_ab12cd34), the Idempotency-Key, the client IP address and user agent.
- Request and response bodies and the
Authorizationheader are never logged. Query parameters that look like secrets (for exampleapi_key,token,secretorsignature) are removed before the query string is stored. - Every response carries an
X-Request-Idheader (your ownX-Request-Idis reused when you send one). Quote it when contacting support. - Successful write calls (
POST,PATCH,PUT,DELETE) also add an entry to your audit log with sourceapiand the key that made the call, next to the actions of your dashboard users.
| Log | Where | Retention |
|---|---|---|
| API requests | Dashboard: Settings > Audit log > API requests | 90 days |
| User and API actions (source, outcome, IP address; filter by user or API keys, action and record) | Dashboard: Settings > Audit log > User actions | Kept |