Skip to Content
Pocket Notifier

Users and access

Invites, project roles and access tokens, and who can do what.

There are two kinds of credentials:

  • People sign in to the web dashboard and the app with email and password. That gives them a better-auth session.
  • Scripts publish with an access token that a person created. A token can never do more than the person who owns it.

Invites

Decided Public sign-up is turned off. New people join through an invite link created in the dashboard.

Create the invite

An existing user creates an invite. Optionally it is locked to one email address, and it can grant memberships in projects the inviter owns. Invites expire after 7 days by default (at most 30).

The link looks like https://<web>/invite/<code>. The 24-character code is the only secret; notifier stores a hash of it.

Sign up

The sign-up page shows who sent the invite and which projects it includes (invites.preview). Creating the account consumes the invite and applies the project grants in the same request.

Invites are single use. They can be revoked until they are accepted.

The first account. A fresh deployment has no one to invite the first person, so sign-up without an invite is allowed while the database has no users. That first account owns the deployment; every account after it needs an invite.

Sign-up request. The invite code goes in the better-auth sign-up body as inviteCode:

{ "name": "Alex", "email": "alex@example.com", "password": "…", "inviteCode": "<24-char code>" }

Without a valid open invite, every sign-up gets the same 403, whether or not the email is already registered.

Implementation note

Sign-up stays a better-auth endpoint. A before hook rejects requests without a valid open invite. The invite is then claimed atomically just before the user row is written, so no account can exist without a claimed invite. After the user is created, memberships are added for granted projects the inviter still owns.

Project roles

Decided Every project has members, and each member has one role. The person who creates a project is its owner.

Actionownerpublishersubscriber
Read history and receive pushes✓✓✓
Reply to and acknowledge messages✓✓✓
Publish messages and upload attachments✓✓
Read replies through the API✓✓
Change project settings and retention✓
Add, change and remove members✓
Delete messages or the project✓
Create features (projects' workstreams)✓✓
Change a feature's status✓

A project can have more than one owner. The last owner cannot leave or be demoted.

Decided Each user also has a private General project (personal: true) that takes notifications sent without a project. Only its owner is ever a member: adding members, granting it in an invite and deleting it are refused.

Membership controls access. A subscription controls pushes: members are subscribed when they join, and each person can unsubscribe or mute a project. A muted project still fills the inbox but sends no push.

Access tokens

Decided Tokens are for anything that is not a person: scripts, CI, servers.

Authorization: Bearer nt_4fK9qL2mXw8RtY1vB6nC3dE7gH0jP5sA9zU2iO4k
  • Format. nt_ followed by 40 base62 characters. Only a hash is stored. The secret is shown once, when the token is created, and the list shows only its first characters (nt_4fK9).
  • Scope. Either all, meaning every project where the owner is owner or publisher (including projects added later), or a list of project names.
  • Effective permission. A token may publish to a project only if it is in the token's scope and the token's owner is currently an owner or publisher there. Removing a person from a project immediately stops their tokens for it.
  • Expiry. Optional, from 1 to 365 days. lastUsedAt is updated on use so stale tokens are easy to spot.

Decided MCP clients (Claude Code, Codex) do not use access tokens. They sign in through the browser with OAuth and act as the signed-in user, with that user's roles. See MCP server.

Decided Tokens live in notifier's own access_token table rather than the better-auth api-key plugin, so the project scope and the contract stay in one place.

What is checked where

On this page