PIN Code

Introduction

PIN code powers parental controls in the Quick Brick Parent Lock plugin (parent-lock-qb). A customer-hosted endpoint receives CloudEvents v1.0 JSON payloads and returns success or error responses that the app uses to grant access, set a PIN, change a PIN, or trigger a reset email.

Remote PIN flows require Enable Remote PIN Verification and a configured PIN Verification Endpoint data source. See Parent Lock for Zapp Studio setup, supported client flows, and the pinCode feed action.

All remote PIN requests POST to the same endpoint URL (remote_type_endpoint.source).

PIN Validation (`com.applicaster.pin.v1`)

Fire when the user submits a PIN on a parental lock screen — the default Remote Verify flow (hook, standalone, or pinCode action with flow: "verify-pin" / "verify").

Cloud event payload:

{
  "specversion": "1.0",
  "type": "com.applicaster.pin.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "subject": "Pin code sent",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "application/json",
  "data": {
    "pin_code": "1234"
  }
}

Success response (HTTP 200 or 201):

{
  "specversion": "1.0",
  "type": "com.applicaster.event.received.v1",
  "source": "<SERVER_URL>",
  "subject": "Valid Pin Code",
  "id": "<submitted-pin-value>",
  "time": "<TIME_IN_RFC3339_FORMAT>"
}

An optional subject message (for example "Valid PIN") is shown briefly in the app before the user proceeds.

Return HTTP 400 when the PIN is invalid. Prefer a JSON body with a message field — the app surfaces error.response.data.message when present.

Set PIN (`com.applicaster.pin.set.v1`)

Fire when the user completes the Set PIN flow (pinCode action with flow: "set-pin"). The client collects the PIN twice (enter → re-enter) before sending the event.

Cloud event payload:

{
  "specversion": "1.0",
  "type": "com.applicaster.pin.set.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "subject": "Set parent lock PIN",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "application/json",
  "data": {
    "pin_code": "1234"
  }
}

Success: HTTP 200 or 201. Return a CloudEvents receipt; an informative subject (for example "PIN set") is shown briefly in the app.

Errors: HTTP 400 with a user-facing message when the PIN cannot be set.

note

Set PIN and Change PIN are blocked on kids profiles (isKidsProfile in session storage).

Change PIN (`com.applicaster.pin.change.v1`)

Fire during the Change PIN flow (pinCode action with flow: "change-pin"). The client sends two events: first to verify the current PIN, then — after the user enters and confirms a new PIN — to commit the change.

Step 1 — Verify current PIN

{
  "specversion": "1.0",
  "type": "com.applicaster.pin.change.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "application/json",
  "data": {
    "step": "verify_current",
    "current_pin_code": "1234"
  }
}

Step 2 — Confirm new PIN

Sent only after the client confirms the new PIN twice.

{
  "specversion": "1.0",
  "type": "com.applicaster.pin.change.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "application/json",
  "data": {
    "step": "confirm_change",
    "current_pin_code": "1234",
    "pin_code": "5678"
  }
}

Success: HTTP 200 or 201 for each step. Optional subject on the final step (for example "PIN changed") is shown briefly.

Errors: HTTP 400 when the current PIN is wrong or the new PIN fails validation.

Reset PIN (`com.applicaster.pin.reset.v1`)

Not implemented in the client

The pinCode action with flow: "reset-pin" returns an error in the current Parent Lock plugin. Do not rely on this event until the client implements it.

The email-based recovery flow below is the supported reset path today.

PIN Reset via email

Users who forgot their PIN can request a reset via email. This is a two-step flow.

Step 1 — Fetch the recover-pin-code feed

Fetch the recover-pin-code feed to get a pre-configured action entry. Render this entry in your UI (for example, a "Forgot PIN?" button).

Feed response:

{
  "id": "<account-token>-recover-pin-code",
  "title": "Recover Pin Code",
  "type": {
    "value": "recover-pin-code-feed"
  },
  "entry": [
    {
      "id": "recover-pin-code",
      "title": "Recover Pin Code",
      "type": {
        "value": "action"
      },
      "extensions": {
        "tap_actions": {
          "actions": [
            {
              "type": "sendCloudEvent",
              "options": {
                "url": "<your-cloud-events-endpoint>",
                "type": "com.applicaster.pin.recovery.requested.v1",
                "subject": "Pin Code Recovery Request",
                "id": "pin_code_recovery_requested"
              }
            }
          ]
        }
      }
    }
  ]
}

The tap_actions on the entry are pre-configured to fire com.applicaster.pin.recovery.requested.v1 when tapped. Wire this entry to a tappable element in your UI — no additional event handling is needed.

Step 2 — PIN reset cloud event fires

When the user taps the action, the app automatically sends com.applicaster.pin.recovery.requested.v1 to your cloud events endpoint.

Success response:

{
  "specversion": "1.0",
  "type": "com.applicaster.event.received.v1",
  "source": "<SERVER_URL>",
  "subject": "Pin Code Recovery Requested",
  "id": "pin_code_recovery_requested",
  "time": "<TIME_IN_RFC3339_FORMAT>"
}

The user receives a PIN reset email at their registered account email address.

`pinCode` feed action

Use the pinCode action to open Parent Lock with an explicit flow and navigate to a destination screen on success.

{
  "type": "pinCode",
  "options": {
    "typeMapping": "target-screen",
    "navigationAction": "push",
    "flow": "verify-pin"
  }
}

Option	Required	Description
`typeMapping`	Yes	Content type of the destination screen after PIN succeeds
`flow`	Yes	`"verify-pin"`, `"verify"`, `"set-pin"`, `"change-pin"`, or `"reset-pin"` (not implemented)
`navigationAction`	No	`"push"` (default) or `"replace"`

typeMapping is the screen to open after Parent Lock succeeds — not the parent-lock screen itself. Replace "target-screen" with your app's content type mapping.

Flow values:

Flow	`options.flow`
Remote Verify	`"verify-pin"` or `"verify"`
Set PIN	`"set-pin"`
Change PIN	`"change-pin"`
Reset PIN	`"reset-pin"` (client returns error today)

Math Challenge does not use pinCode — use a hook or navigateToScreen with remote PIN disabled in the manifest.

Server response guidelines

Return HTTP 200 or 201 on success. The Parent Lock plugin treats both as success.
Return HTTP 400 for invalid PIN or validation failures. Prefer { "message": "..." } in the response body.
Optional CloudEvents receipt subject values are shown briefly in the app before finish.
time fields must be RFC3339, for example 2021-04-12T23:20:50.52Z.
Do not log raw PIN values server-side.

Cloud Event Reference

Event type	Purpose	Client trigger	Response subject (typical)
`com.applicaster.pin.v1`	Validate a PIN	Remote Verify flow	`"Valid Pin Code"`
`com.applicaster.pin.set.v1`	Set a new PIN	Set PIN flow	Custom (for example `"PIN set"`)
`com.applicaster.pin.change.v1`	Change PIN (two steps)	Change PIN flow	Custom (for example `"PIN changed"`)
`com.applicaster.pin.reset.v1`	Reset PIN	Not implemented client-side	—
`com.applicaster.pin.recovery.requested.v1`	Request PIN reset via email	Recover PIN feed action	`"Pin Code Recovery Requested"`

See also the Cloud Events reference for event entries in the full protocol catalog.

Introduction​

PIN Validation (com.applicaster.pin.v1)​

Set PIN (com.applicaster.pin.set.v1)​

Change PIN (com.applicaster.pin.change.v1)​

Step 1 — Verify current PIN​

Step 2 — Confirm new PIN​

Reset PIN (com.applicaster.pin.reset.v1)​

PIN Reset via email​

Step 1 — Fetch the recover-pin-code feed​

Step 2 — PIN reset cloud event fires​

pinCode feed action​

Server response guidelines​

Cloud Event Reference​