PIN Code

Introduction

PIN code is used for parental controls — it lets apps verify a numeric PIN before granting access to age-restricted content or screens. The flow involves two cloud events and a recovery feed: validate a PIN against an account, or trigger a PIN reset email.

To use PIN code in your app, configure the Parent Lock plugin to use Remote PIN Verification mode. See Parent Lock for plugin setup.

PIN Validation

Fire the com.applicaster.pin.v1 cloud event when the user submits a PIN on a parental lock screen.

Cloud event payload:

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

Success response:

{
  "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 HTTP 400 response is returned when the PIN is invalid. Surface an error to the user in this case.

PIN Reset

Users who have forgotten 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 (e.g., 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.

Cloud Event Reference

Event type	Purpose	Trigger	Response subject
com.applicaster.pin.v1	Validate a PIN	User submits PIN on parental lock screen	"Valid Pin Code"
com.applicaster.pin.recovery.requested.v1	Request PIN reset via email	User taps "Recover Pin Code" action	"Pin Code Recovery Requested"