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.

Before you beginUse an authorized administrator account and confirm the business shown in the top bar. Record the previous value before changing a live operational setting.

Step by step

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. 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.
  13. 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.
  14. 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.
  15. 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.
  16. 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.
  17. 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.
  18. 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.
  19. 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 areaWhat it means
Current companyGlobal company context that owns every client, key, endpoint, request log, and delivery visible on the page.
Plan capacityUp to limits for clients, active keys, and webhook endpoints; not a count of resources already created.
Integration clientTenant-bound administrative container for one external application or automation.
Default scopesLeast-privilege permissions proposed when keys are issued under the client.
Test environmentRestricted key routed only to an assigned isolated preview data plane.
Live environmentRestricted key routed only to the company’s approved active dedicated data plane.
One-time key revealOnly opportunity to capture the raw cp_test_ or cp_live_ secret; CentriPOS stores a keyed digest rather than the raw value.
ExpirationOptional key lifetime boundary; expired keys fail authentication.
RevokeImmediately disables the key while preserving immutable audit history.
Authenticated liveOperation available only for an explicitly entitled tenant and correctly scoped key.
Controlled rolloutDocumented operation that remains fail-closed until its independent activation gates pass.
Request logAppend-only safe metadata for admitted and rejected API activity; no raw keys, request bodies, or response payloads.
Webhook endpointTenant- and client-bound HTTPS receiver subscribed to explicit approved event types.
Signing secretOne-time HMAC secret used by the receiver to authenticate CentriPOS webhook deliveries.
webhook.testSynthetic event used to verify endpoint connectivity and signature handling.
Delivery logAttempt status, response, timing, retry, and error metadata for signed webhook delivery.
Event safe snapshotComplete event-specific allowlisted scalar projection embedded in data.object; protected, credential, payment, arbitrary JSON, and portal-secret fields are excluded.
Deleted tombstoneIdentity-only deleted-resource object with id, object, optional changed_fields, and resource_url.
Resource URLBranded Retail API URL used with a separately scoped key to retrieve the current supported resource.
No exact screenshotThe 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.

More guides

Build an itemized payment in MoneyUse Products or Amount & description to build one receipt, attach the customer, and follow the appropriate payment or service-estimate workflow.
Take a one-time payment in Virtual TerminalReview a one-time amount, tax and contact at the correct payment station, use its verified secure checkout, and recover the original receipt after an uncertain result.
Review booking payments, refunds and earned careKeep a booking’s customer payments, unused advances, completed care, cancellation fees and refunds distinct, then read a correctly scoped accrual report.
Configure booking properties and customer pagesSet accommodations, service packages, availability, required intake and payment terms, then review the correctly branded booking page before sharing it.