Authentication

Publishable keys exchange for a short-lived access token. That token is the credential for every gateway call.

On this page

Publishable key

  1. Sign up at app.comprehendly.nz/signup.
  2. Author a form and publish it. Catalog and fill only return published pages.
  3. Settings → API → create a publishable key (pk_test_ or pk_live_).

Do not put pk_* on an iframe query string. Exchange first, then pass the token.

Origin allowlist

Each key lists allowed origins (scheme + host + port, no path). The request Origin header must match one entry exactly.

Client Typical origin
JS demo http://localhost:4173
Swift (SDK default) https://ios-demo.comprehendly.nz

Browsers set Origin themselves. Native clients must set the header (ComprehendlyClient.origin). file:// pages have no usable origin — serve over HTTP.

Scopes

Minimum for catalog, page, fill, and save:

forms.schemas:read
forms.submissions:read
forms.submissions:write

forms.schemas:read is the catalog/page permission. There is no separate schema-form API.

Exchange

POST https://api.stepcare.app/functions/v1/integration_exchange 

{
  "key": "pk_test_…",
  "audience": "stepcare-embed",
  "requested_scopes": [
    "forms.schemas:read",
    "forms.submissions:read",
    "forms.submissions:write"
  ]
}

Send the platform anon key as apikey and Authorization: Bearer (same as forms.js). SDKs do this in exchange().

Response: access_token, expires_in (seconds), tenant_id, scopes.

Gateway

POST https://api.stepcare.app/functions/v1/integration_gateway 

{
  "access_token": "scist_…",
  "operation": "forms.catalog.list",
  "params": {}
}

Success envelope: { "data": …, "request_id": "uuid" }. SDKs return data. Error shape: Errors.

PreviousQuickstart NextConcepts