Create user notification channel

Outcome

Register a pending address or return the existing exact duplicate without metadata updates; no ownership challenge is sent.

These examples prove local handler behavior with real isolated notification SQL and explicitly simulated identity dependencies.

Before you start

• Verify pinned identity and the exact published action. Preference/address storage permits self or platform authority; organization admin alone cannot manage another user. Organization forbid rules require authority over the exact organization.

• Discover the intended user/org independently. These storage handlers do not verify target existence and stored preference lists do not resolve effective delivery. Omitted preference org_id means global wildcard *, while replacement selects organization scope through query.org_id.

• Before replacement capture the complete previous scope, review the full intended rows and inspect the validated plan. Empty rows clears explicit rules and may permit more delivery. Replacement is sequential and can leave partial state.

• Channel verify only sets a stored flag and performs no possession challenge. Retain independent authorized ownership evidence before approving it; fixture addresses are unused and authorize no live verification or outreach.

Discover the target

topolo whoami --json
topolo apps --json
topolo actions get app_topolo_auth.user_notification_channels.create --detail --json

Discover the authorized target user and exact organization. Read user_notification_preferences.list for each scope separately, user_notification_channels.list for stored channel_id values, or organization_notification_policy.list for the managed organization. Copy ids only from the exact selected scope. Effective delivery requires the published resolve action and delivery read-back separately.

Input fields

Effects

• Creates a pending notification address or returns the existing exact duplicate without updating it.

• No challenge or message is sent; primary account identity is unchanged.

Interpret the response

Registers an address with verified_at null and returns HTTP 201. A duplicate exact user/channel/trimmed-address returns the old row at 201 without updating label, metadata or verification.

The handler sends no ownership challenge or message and does not change primary account email. channel may be null if post-write read cannot find the row; require nonnull exact-user/id/address read-back before treating registration as verified.

Worked examples

These are complete raw target-handler responses, not CLI/gateway envelopes or live authorization proof. Synthetic users, organizations and unused addresses exist only in isolated fixtures. Discover real intended targets and review effects separately. Save only reviewed input as payload.json; validate and inspect the unchanged plan before an authorized call. --confirm assumes intended approval. Cookie/Bearer identities must consistently select the intended principal. Stored rows, ownership evidence, effective policy and actual delivered messages are separate outcomes. No fixture sends a message or performs an address challenge.

Register a pending address without sending any ownership challenge

Input · payload.json:

{
  "userId": "usr_self",
  "channel": "email",
  "address": "fixture-address@example.test",
  "label": "Fixture email",
  "metadata": {
    "source": "isolated-doc-fixture"
  }
}

CLI:

topolo actions validate app_topolo_auth.user_notification_channels.create --data @payload.json --json
topolo actions plan app_topolo_auth.user_notification_channels.create --data @payload.json --confirm --json
topolo actions call app_topolo_auth.user_notification_channels.create --data @payload.json --confirm --json

MCP call after validation and plan review:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_notification_channels.create",
    "input": {
      "userId": "usr_self",
      "channel": "email",
      "address": "fixture-address@example.test",
      "label": "Fixture email",
      "metadata": {
        "source": "isolated-doc-fixture"
      }
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 201:

{
  "success": true,
  "message": "Notification channel registered",
  "data": {
    "userId": "usr_self",
    "channel": {
      "channel_id": "nch_DUthNOwIONWASRT_",
      "user_id": "usr_self",
      "channel": "email",
      "address": "fixture-address@example.test",
      "label": "Fixture email",
      "metadata_json": "{\"source\":\"isolated-doc-fixture\"}",
      "verified_at": null,
      "created_at": 1790971419
    }
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Duplicate user/channel/address returns the existing row without updating label or metadata

Input · payload.json:

{
  "userId": "usr_self",
  "channel": "email",
  "address": "fixture-address@example.test",
  "label": "Changed label ignored",
  "metadata": {
    "ignored": true
  }
}

CLI:

topolo actions validate app_topolo_auth.user_notification_channels.create --data @payload.json --json
topolo actions plan app_topolo_auth.user_notification_channels.create --data @payload.json --confirm --json
topolo actions call app_topolo_auth.user_notification_channels.create --data @payload.json --confirm --json

MCP call after validation and plan review:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_notification_channels.create",
    "input": {
      "userId": "usr_self",
      "channel": "email",
      "address": "fixture-address@example.test",
      "label": "Changed label ignored",
      "metadata": {
        "ignored": true
      }
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 201:

{
  "success": true,
  "message": "Notification channel registered",
  "data": {
    "userId": "usr_self",
    "channel": {
      "channel_id": "nch_DUthNOwIONWASRT_",
      "user_id": "usr_self",
      "channel": "email",
      "address": "fixture-address@example.test",
      "label": "Fixture email",
      "metadata_json": "{\"source\":\"isolated-doc-fixture\"}",
      "verified_at": null,
      "created_at": 1790971419
    }
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Push address registration stores opaque synthetic address without device delivery proof

Input · payload.json:

{
  "userId": "usr_self",
  "channel": "push",
  "address": "unusable-fixture-push-address"
}

CLI:

topolo actions validate app_topolo_auth.user_notification_channels.create --data @payload.json --json
topolo actions plan app_topolo_auth.user_notification_channels.create --data @payload.json --confirm --json
topolo actions call app_topolo_auth.user_notification_channels.create --data @payload.json --confirm --json

MCP call after validation and plan review:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_notification_channels.create",
    "input": {
      "userId": "usr_self",
      "channel": "push",
      "address": "unusable-fixture-push-address"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 201:

{
  "success": true,
  "message": "Notification channel registered",
  "data": {
    "userId": "usr_self",
    "channel": {
      "channel_id": "nch_mPQVYgYmwm8cHAjT",
      "user_id": "usr_self",
      "channel": "push",
      "address": "unusable-fixture-push-address",
      "label": null,
      "metadata_json": null,
      "verified_at": null,
      "created_at": 1790971419
    }
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Verify the result

• Require a nonnull response channel for the selected user, channel and trimmed address; read user_notification_channels.list for that exact row.

• Inspect existing label/metadata/verification on duplicates; do not assume newly supplied metadata was applied. Independently verify ownership before any flag mutation.

Errors and recovery

Anonymous address creation is refused

Captured local refusal · HTTP 401:

{
  "input": {
    "userId": "usr_self",
    "channel": "email",
    "address": "fixture-address@example.test",
    "label": "Fixture email",
    "metadata": {
      "source": "isolated-doc-fixture"
    }
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access token required",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Email address format is validated beyond the generic id input

Captured local refusal · HTTP 400:

{
  "input": {
    "userId": "usr_self",
    "channel": "email",
    "address": "not-an-email",
    "label": "Fixture email",
    "metadata": {
      "source": "isolated-doc-fixture"
    }
  },
  "response": {
    "success": false,
    "error": {
      "message": "Invalid channel payload",
      "code": "VALIDATION_ERROR",
      "details": [
        "address must be a valid email"
      ],
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Published recovery guidance

• state_conflict (HTTP 409): Read the current resource state, reconcile the intended change, and retry only if still valid.

• AUTH_ERROR (HTTP 401): Verify pinned identity. If authenticated, respect self/platform user authority or exact organization management denial; organization ownership alone does not authorize another user address/preferences. Do not assume OAuth expiry or change context automatically.

• VALIDATION_ERROR (HTTP 400): Correct the reported fields only. Use unique event/channel pairs and valid channel-specific addresses. Validate and review the exact complete replacement again before approval.

• NOT_FOUND (HTTP 404): Refresh the target user channels list. A row for another user is not authorized by a known channel id; repeated delete is already absent, not a new successful deletion.

• SERVER_ERROR (HTTP 500): Preserve the result and read the exact stored scope before any new write. A replacement may have deleted old rules and inserted only some new ones; review finishing the intended set or restoring the captured set as a new approved replacement.

Recovery boundaries

Delete only a newly created unwanted row after separate approval and exact-user read-back. A duplicate response may be a pre-existing route; do not delete it as rollback. Deletion does not cancel queued messages or undo deliveries.

Discovery and evidence

This record belongs to app_topolo_auth. Fixtures prove actual NotificationPreferencesController and AuthController authority, validation, canonical notification SQL, duplicate/address identity and sequential replacement failure boundaries. Authenticated identities and unused targets/addresses are simulated and second-insert SQL failures injected. No live storage, ownership challenge, notification, deployment or production publication is proved.