Security

A Kentro API key is a tenant credential: whoever holds its secret acts as the integration it was made for. These rules keep keys, buyer sessions and customer data where they belong.

Handle secrets

• Kentro shows a key's secret once, at creation, and cannot show it again. Store it in a secrets manager or the hosting platform's encrypted environment variables.
• Never put a secret, a bearer token or a refresh token in a URL, a log line, an error report, a support email, source control or client-side code.
• Log the key's public Key value and the request id instead; both are safe to share.
• Use one key per integration and per environment, so a leak is contained to one system.

Server side only

• The Store API is server-to-server. A browser never calls it: the API key is a tenant credential, and the API answers with no CORS headers for tenant origins.
• Buyer tokens and guest tokens stay on the storefront server, mapped to the storefront's own session cookie. The browser holds only that cookie.
• One guest token is one visitor's cart: never reuse it across browsers.
• Send X-Expected-Buyer (and X-Expected-Portal) with the identity the server's session holds, so a browser whose session changed is answered 409 CONFLICT instead of acting on another account.
• Never take a tenant id, a store id or a buyer id from the browser. The tenant comes from the key, the store from the host, the buyer from the token the server holds.
• The Channel API is for servers too: no browser, mobile app or desktop client holds a key pair.
• Kentro Pixel public keys are the exception: they are meant to be visible in page source, and the property's allowed origins limit where they work. Pixel server keys stay on the server.

Least privilege

• Give each integration its own permission group with only the scopes it uses. Per-resource write scopes need channel:read for reads; see API keys and scopes.
• Bind each key to the sales channels it writes into.
• API keys carry no IP restriction: scopes and channel bindings are the controls.
• Disable keys nobody uses with their Active toggle. Kentro OS shows when a key was created, not when it was last used, so keep a record of which system holds which key.
• Rotate keys on a schedule, when people who saw a secret leave, and at once after a suspected leak.

Tenant isolation

• The credential decides the tenant. Nothing in a header, a body or a query string selects one.
• An id from another tenant answers as if it did not exist: 404 not_found on the Channel API. A Store API host that belongs to another tenant answers 403 FORBIDDEN "This storefront belongs to another account."

Inbound traffic and signatures

• Neither the Channel API nor the Store API calls your systems: integrations poll, so they need no endpoint open to Kentro.
• Kentro Pixel server events are signed by the sender with HMAC-SHA256 and a timestamp; the collector accepts signatures within a 300-second window. See Pixel server API.
• Kentro Pixel webhook destinations deliver to an https:// URL with a public host name; see Pixel destinations.

Data protection

• Send only the data an integration needs. The Channel API refuses unknown fields (400 validation_failed) instead of storing them.
• Card numbers never go to a Kentro API. Store API checkout hands payment to the store's provider (redirectUrl, clientSecret or a hosted card form), and saved cards are stored by the provider.
• Buyer password reset answers the same body whether or not an account exists, so it reveals nothing about which addresses have accounts.
• Kentro Pixel replaces raw email and phone values with SHA-256 hashes, never stores the raw IP address, and quarantines payloads that look like health data, secrets or card numbers. See Pixel consent and privacy.

Kentro MCP

A Kentro MCP connection acts with the permissions of the user who approved it. The user revokes it in Kentro IQ under Assistant > Assistant Settings, panel Connect your AI tools (MCP). See MCP security.

When a secret leaks

1. Turn off the key's Active toggle in Users > API keys.
2. Generate a replacement key and deploy it.
3. Write to [email protected] with the leaked key's public Key value, never the secret, and the time window of the exposure.