Admin → API Center is the merchant control plane for private CentriPOS integrations. Access is subscription- and rollout-gated. A credential is bound to the current company, one client, one environment, and explicit scopes; callers never supply a tenant ID or data-plane route. Raw key and signing-secret values are shown once.
Step by step
- Go to Admin → API Center and confirm the company name in the global header before doing anything. API resources are isolated to that selected company. The capacity row says Up to and describes plan limits, not existing clients, keys, or endpoints.
- Read the entitlement banner. Developer API not included means new credentials and operational delivery are blocked. Live access included permits approved read requests against the active dedicated data plane. Test access requires an assigned isolated preview data plane; it never falls back to live.
- Create a separate integration client for each external application, agency, or automation. Enter an owner-readable name and purpose. Select only the default scopes the integration genuinely needs. A client is an administrative boundary, not a secret by itself.
- Treat read and write scopes separately. Event integrations use events:read/write for offerings and publication, events:registrations:read/write for enrollment records, events:attendance:read/write for atomic attendance, events:credentials:read/write for ticket credential issuance and lifecycle, and events:sensitive:read/write only for specifically authorized protected participant, answer, or consent data. Calendar, reports, audit, webhooks, and every other domain have separate scopes. Controlled operations remain disabled until their operation-specific rollout gate passes.
- Issue a key from the intended client. Choose Test or Live only when the matching environment is approved, give the key a narrow name, review its scopes, and set an expiration appropriate to the integration. Never grant cost, sensitive-event, or attendance-credential scopes unless the caller genuinely needs them.
- Capture the raw key from the one-time reveal into the integration’s server-side secret manager. Do not put it in browser JavaScript, a mobile bundle, source control, analytics, screenshots, tickets, URLs, query strings, or the public support-site explorer. CentriPOS retains only a keyed digest, prefix, last four, environment, scope, and lifecycle metadata.
- Call the branded https://pos.getcentri.com/api/retail/v1 base from the integration server using Authorization: Bearer <restricted key> and Accept: application/json. Do not send a tenant ID, Supabase hostname, project reference, database route, or service-role credential.
- Use the date-pinned Retail API OpenAPI contract on support.centripos.com. Operations marked Authenticated live are available only to explicitly entitled tenants with the required scope. Controlled rollout operations remain documented but fail closed until enabled.
- For every response, record X-Request-ID and the HTTP status. A 401 means the credential is missing, malformed, expired, or revoked. A 403 means the key is valid but lacks scope or tenant policy. A 503 operation_not_enabled means the contract exists but execution is still gated.
- Open Request log to inspect the admitted request ID, client, key, environment, version, operation, scope, method, route template, result, duration, response size, rate-limit decision, idempotency result, safe user-agent metadata, and error code. Request bodies, response payloads, and raw credentials are not stored in this log.
- Create a webhook endpoint under the client only after the receiving HTTPS service is ready. Give it a clear name, choose the correct environment, enter the exact HTTPS URL, and subscribe only to the event types that company has authorized. Operational events require the matching subscription entitlement and the client must retain the matching resource-read scope.
- Capture the one-time signing secret in the receiver’s secret manager. Read CentriPOS-Signature in t=<timestamp>,v1=<hex> form and verify HMAC-SHA256 over <timestamp>.<exact raw JSON body> before parsing or trusting the body. Enforce the replay window, deduplicate the immutable event ID, and correlate CentriPOS-Delivery-ID, CentriPOS-Event, and CentriPOS-API-Version.
- Event and calendar webhook bodies include the complete allowlisted scalar safe snapshot for that resource inline in data.object, plus changed_fields when supplied and a branded resource_url when an item route exists. They never embed arbitrary JSON metadata, registration answers, medical or accessibility details, waiver signature evidence, ticket credentials, payment data, or portal secrets. Deleted resources are identity-only tombstones. General or legacy domain webhooks may still use bounded notification projections; inspect the event-specific OpenAPI contract.
- Use resource_url with a separately scoped key when the receiver needs a fresher or broader supported representation. The inline event snapshot is immutable delivery evidence, not a substitute for scope-gated retrieval and never permission to query internal tables.
- Use the delivery log to inspect queued, succeeded, retrying, and failed attempts. Test sends a synthetic webhook.test event. Runtime delivery treats 2xx as success and makes up to six total attempts with bounded exponential backoff and jitter. Retry only after the receiver is corrected; consumers must remain idempotent because legitimate retries retain the same event ID.
- Pause an endpoint before planned receiver maintenance and resume it only when signature verification and idempotency are healthy. Rotate a webhook signing secret deliberately and update the receiver during the supported overlap. Disable endpoints no longer owned by an active integration.
- Rotate or revoke an API key immediately when it may have been exposed, an integration changes ownership, or its scope is no longer appropriate. Revocation is immediate and does not delete immutable request history. Issue the replacement first only when an approved overlap is required.
- Keep one client per integration and one narrowly scoped key per environment. Do not share a merchant, agency, or platform credential with another tenant. Branding, subscription entitlement, environment, rate limits, audit history, and webhook subscriptions all remain attached to the exact selected company.
- Before certifying an integration, verify missing-key rejection, wrong-scope rejection, test/live isolation, tenant isolation, rate limiting, expiration and revocation, complete supported payload shape, request-log correlation, webhook signature rejection, retry deduplication, and fail-closed mutations.
Screen and contract reference
| Control or area | What it means |
|---|---|
| Current company | Global company context that owns every client, key, endpoint, request log, and delivery visible on the page. |
| Plan capacity | Up to limits for clients, active keys, and webhook endpoints; not a count of resources already created. |
| Integration client | Tenant-bound administrative container for one external application or automation. |
| Default scopes | Least-privilege permissions proposed when keys are issued under the client. |
| Test environment | Restricted key routed only to an assigned isolated preview data plane. |
| Live environment | Restricted key routed only to the company’s approved active dedicated data plane. |
| One-time key reveal | Only opportunity to capture the raw cp_test_ or cp_live_ secret; CentriPOS stores a keyed digest rather than the raw value. |
| Expiration | Optional key lifetime boundary; expired keys fail authentication. |
| Revoke | Immediately disables the key while preserving immutable audit history. |
| Authenticated live | Operation available only for an explicitly entitled tenant and correctly scoped key. |
| Controlled rollout | Documented operation that remains fail-closed until its independent activation gates pass. |
| Request log | Append-only safe metadata for admitted and rejected API activity; no raw keys, request bodies, or response payloads. |
| Webhook endpoint | Tenant- and client-bound HTTPS receiver subscribed to explicit approved event types. |
| Signing secret | One-time HMAC secret used by the receiver to authenticate CentriPOS webhook deliveries. |
| webhook.test | Synthetic event used to verify endpoint connectivity and signature handling. |
| Delivery log | Attempt status, response, timing, retry, and error metadata for signed webhook delivery. |
| Event safe snapshot | Complete event-specific allowlisted scalar projection embedded in data.object; protected, credential, payment, arbitrary JSON, and portal-secret fields are excluded. |
| Deleted tombstone | Identity-only deleted-resource object with id, object, optional changed_fields, and resource_url. |
| Resource URL | Branded Retail API URL used with a separately scoped key to retrieve the current supported resource. |
| No exact screenshot | The public guide intentionally contains no real merchant key, endpoint URL, signing secret, request log, or private payload capture. |
Expected result
This workflow is complete only after CentriPOS reflects the intended result. Final checkpoint: Before certifying an integration, verify missing-key rejection, wrong-scope rejection, test/live isolation, tenant isolation, rate limiting, expiration and revocation, complete supported payload shape, request-log correlation, webhook signature rejection, retry deduplication, and fail-closed mutations.
Troubleshooting
- Confirm you are changing the intended business and location before saving.
- Record the previous setting when a change affects live selling, payments, tax, or integrations.
- Use a controlled test record after saving before rolling the setting out broadly.
CentriPOS API explorer · API Center administration