# 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](/using-zapp/auth/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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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"` |