> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Gate API overview

> Public and portal API endpoints for Customer Gate, including authentication and request examples.

# 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

```bash theme={null}
curl --fail-with-body "${APP_ORIGIN:?Set APP_ORIGIN}/healthz"
```

`/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.

```bash theme={null}
curl "${APP_ORIGIN:?Set APP_ORIGIN}/public/forms/wholesale-application" \
  -H "X-Pcnaid-Form-Key: ${FORM_KEY}"
```

### 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.

```bash theme={null}
curl "${APP_ORIGIN:?Set APP_ORIGIN}/public/submit" \
  -H "X-Pcnaid-Form-Key: ${FORM_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"slug":"wholesale-application","email":"buyer@example.com","data":{"company_name":"Acme"}}'
```

### 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.

```bash theme={null}
curl "${APP_ORIGIN:?Set APP_ORIGIN}/public/access" \
  -H "X-Pcnaid-Form-Key: ${FORM_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"surface":"storefront"}'
```

## 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.

```bash theme={null}
curl "${APP_ORIGIN:?Set APP_ORIGIN}/public/portal/status" \
  -H "Authorization: Bearer ${CUSTOMER_ACCOUNT_SESSION_TOKEN}"
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.