Skip to main content

​
Customer Gate API overview

Customer Gate exposes a public form API for storefront applications and an authenticated portal API for the customer-account extension. Both are served from the app origin and, for the form endpoints, also from the /apps/customer-gate Shopify app proxy path.

​
Authentication

The public form API uses the X-Pcnaid-Form-Key header. The tenant is derived exclusively from that key, never from a request-body or query-string shop value. A supplied Origin must exactly match the key’s allowlist; callers without an Origin remain supported. The key is issued and rotated from the embedded app’s Settings page. Login-required forms and the portal endpoints require a verified Shopify customer-account session token in Authorization: Bearer <session-token>. Customer identity is derived only from the token’s verified sub claim. Portal endpoints use that customer identity instead of a public form key. Set APP_ORIGIN to the app’s HTTPS origin, without a trailing slash. It is the part of the Submission URL shown on the embedded app’s Settings page before /public/submit. Every example below uses it.

​
Health

/health reports liveness and the deployed release SHA. /healthz additionally queries PostgreSQL and returns database: "ok" with the same release SHA.

​
Public form API

​
GET /public/forms/:slug

Returns the safe published form definition consumed by the theme block: name, slug, journey type, login requirement, fields, and steps.

​
POST /public/submit

Submits an application. The body includes slug, email, optional customerGid/companyGid, and data keyed by field. Unknown fields, missing required fields, invalid select options, and type mismatches are rejected.

​
POST /public/documents

Attaches a supporting document to a submission. Accepts signature-verified PDF, PNG, or JPEG content up to 10 MiB. When a submission is linked to a customer, the request must include a matching customer-account token.

​
POST /public/access

Evaluates active access rules for a surface and optional resource, returning { "evaluation": ... }. The body accepts surface, optional resourceGid, and legacy tags, customerGid, and companyGid fields for wire compatibility; caller-supplied tags and company GIDs are never used to grant access.

​
Customer portal API

These endpoints require a fresh Shopify customer-account session token and return only the authenticated customer’s data.
  • GET /public/portal/status — returns the customer’s applications, pending count, and the customer_account access evaluation.
  • GET /public/portal/status/:id — returns one of the customer’s applications.
  • GET /public/portal/forms/:slug — loads a login-required form definition.
  • POST /public/portal/submit — submits a form with the authenticated customer identity.
  • POST /public/portal/documents — uploads a supporting document bound to the customer’s own submission.

​
App proxy

The /apps/customer-gate Shopify app proxy path mounts the same public form routes, so the theme block can submit through the store’s configured proxy path.