Access and permissions

Access in Unhandled has two layers. Your role in the organization decides what you can change. Your teams decide which projects you can see. This page covers both, plus the keys that services and CI pipelines use instead of a login.

Roles

An organization has two roles: Admin and Member. There are no per-project roles.

Members can still open the settings pages for members, teams, integrations and issue triage to see how things are set up. Everyone manages their own account: profile, email preferences, sign-in methods and sessions, plus their inbox. Anyone can also create a new organization and becomes its admin.

An organization always keeps at least one admin. Unhandled refuses to demote or remove the last one, refuses to let them leave, and blocks them from deleting their account until another admin exists or the organization is deleted.

Teams and project access

Teams connect members to projects. A team has a name, up to 80 characters and unique in the organization, a set of members and a set of projects. A member can be in several teams, and a project can belong to several teams. A member sees a project when at least one of their teams has it.

Projects a member cannot see do not exist for them: the project list leaves them out, and opening one by URL returns not found rather than forbidden.

Admins see every project whether or not they belong to a team that has it. Admins manage teams under Settings > Teams (/o/:org/settings/teams). Members can open that page too, but it only lists the projects they can already open.

When you sign up

A new organization comes with a team called General and a project called Default. You are an admin, a member of General, and Default is assigned to General. Projects you create later are not assigned to any team. Add them to a team so members can see them.

Invitations

Admins invite people from Settings > Members (/o/:org/settings/members) by email, choosing Admin or Member. An admin has to verify their own email address before inviting anyone. The invitation link is valid for 7 days. Inviting the same address again replaces the pending invitation, and an address that already belongs to a member is rejected.

The invitation can only be accepted by signing in with the invited email address. Opening the emailed link proves you own that address, so accepting through it also verifies your account. Accepting from the dashboard, without the link, needs an account whose address is already verified. A new member starts with no teams, so they see no projects until an admin adds them to a team. A new admin sees every project right away.

Removing a member also removes them from every team in the organization. Emails already queued for them, such as an alert held by a snooze or a message waiting for a retry, are not sent once they leave the organization or lose access to the project the email is about.

Notifications follow access

Everyone who can see a project is a "project member" for notifications: admins plus the members of its teams. Issue assignees must be project members, and uptime, alert and exception emails go to project members. See Notifications.

Keys

Services and pipelines authenticate with keys, not user accounts. Unhandled issues two kinds.

Service keys

Each service has an API key that it sends with its telemetry, packaged in its DSN. Keys start with uh_live_ and are tied to one service. Unhandled stores only a hash and the last four characters, so the full DSN is shown once, when it is issued.

Admins manage keys from the project's services page. Rotating issues a new DSN and keeps the current key working for the grace period you pick: none, 1 hour, 24 hours or 7 days. Revoking stops ingestion for the service, including any key still in its grace period, until you rotate again. Deleting a service also stops its keys from working. See Services for setup.

Service keys can send telemetry. They cannot declare deployments or upload source maps, because a DSN may end up in a browser bundle where anyone can read it.

Deploy keys

Deploy keys let CI declare deployments. They belong to a project, start with dk_, and are shown once at creation. Admins create and revoke them under Settings > Deploy keys; the list shows each key's name, last four characters, last use and creation time.

Deploy keys can call the deployments and source map endpoints, for the services of their own project. They cannot send telemetry. Each key is limited to 60 requests per minute across both. See Deployments API.

Note. Create one deploy key per pipeline. Revoking one then stops only that pipeline.

The MCP server

The MCP server acts as the signed-in user and sees the same projects. A call is allowed only when three things allow it:

• the scopes you granted the connection;
• the organization's MCP policy, which admins set in Settings, MCP: MCP access on or off, and the most an app may do there;
• your role, checked with the same policy as the page the tool mirrors.

Anything that depends on what a connection may do in one organization, such as whether a result may include a heartbeat URL, uses the scopes left after the organization's policy, not the full grant.

A connection can reach every organization you belong to, including ones you join later, or only the ones you pick. A connection limited to the ones you picked never grows on its own. Joining an organization through accept_invitation adds it only to a connection for all organizations; add it to any other under Connected apps.

Admins can cut any app off from their organization without affecting the member's other organizations. The cut-off lasts: editing the connection, or leaving and rejoining the organization, does not lift it.

Tools whose arguments would delete, stop, publish or weaken something ask for confirm: true first. Examples are demoting an admin, emptying a team, posting a public status incident and turning off secret scrubbing.

Suspended organizations

Staff running the installation can suspend an organization from the admin console. Members of a suspended organization can still read everything, but every change in the app is refused, and so are deploy keys and every MCP tool that changes something. Its telemetry is refused at ingest.

Authorization in the code

The rules above are enforced server-side with Bouncer policies in app/policies:

Monitors, status pages, incidents, custom domains and deploy keys require both project visibility and the admin role.