Roles and provenance

All plans Nitsor records people, agent credentials and model Agents as distinct principals. Account roles, project rungs and credential scopes determine what each principal can do.

Identity, role, and permission

An identity answers “who or what is acting?” Nitsor knows three principal types, and every event, Decision and Ledger entry records which one acted:

Principal type	Who	How it authenticates
`user`	A person, keyed by identity-provider issuer and subject.	Dashboard sign-in through WorkOS AuthKit on hosted plans. A Community deployment has no Nitsor dashboard or sign-in, because the self-host stack does not include the Nitsor application. The public API accepts agent credentials, not human sessions.
`agent`	A token of a service account that an owner or admin created (the guides call it an agent token), or a hosted model Agent from the roster.	`Authorization: Bearer <token>`; only the SHA-256 of the token is stored.
`system`	The control plane acting on its own rules: safety checkpoints, lease cleanup, retention sweeps.	Not callable.

Workspace roles control account permissions. Project access levels control actions within a project; Nitsor calls a project access level a rung. Credential scopes limit API access. None of the three implies another.

Workspace roles

A workspace is an account. A member holds one of four roles; the matrix below is the permission table in the code.

Permission	Owner	Admin	Member	Billing
`account:read`	Yes	Yes	Yes	Yes
`account:update`	Yes	Yes	No	No
`members:read`	Yes	Yes	Yes	No
`members:write`	Yes	Yes	No	No
`billing:read`	Yes	Yes	No	Yes
`billing:write`	Yes	No	No	Yes
`storage:read`	Yes	Yes	Yes	No
`storage:write`	Yes	Yes	No	No
`sources:register`	Yes	Yes	No	No
`notifications:read`	Yes	Yes	Yes	No
`notifications:write`	Yes	Yes	No	No
`projects:read`	Yes	Yes	Yes	No
`projects:write`	Yes	Yes	No	No
`work:contribute`	Yes	Yes	Yes	No
`clearance:write`	Yes	Yes	No	No

An admin holds every permission except billing:write, which stays with the owner and the billing role. The matrix shows what each role holds by itself. An owner or admin can also give one member two capabilities on top of their role, from Team settings, Members: Register and retry Sources (sources:register) and Manage storage connections (storage:write). Source access (sources:browse) works the same way when the account has made it explicit instead of giving it to every member. Nothing else on the matrix can be given to a member this way. A plain member can read the account, the roster, storage and notifications, create nothing at account level, and hold work:contribute, the floor that lets them claim, complete, review and commit annotations on projects they have been given a rung on. projects:write covers creating a project, binding routers and approving merges. What a person may do inside a project is decided by the rung, not by the role. Billing pages exist only on hosted plans. Community deployments turn billing off. Enterprise single sign-on uses the organization’s identity provider.

Project rungs

Inside a project, authority is one of four rungs, each including the ones below it: read, contribute, operate, admin. A rung is held through a grant row, per principal, per project. Account owners and admins hold admin on every project of the account without a row. Everyone else holds only what a grant on the project’s Access page (project Settings, then Access) gave them. There are no deny rules; exclusion is the absence of a row.

Rung	What it allows, from the action table
`read`	Open the project; list branches, commits, tasks, datasets and executions; read the taxonomy and pipeline; open a Dataset Version read session and pin it.
`contribute`	Claim, complete, skip, release and take the next Task; record review verdicts; commit annotations; decide a prelabel proposal; write task comments.
`operate`	Create branches and commits, merge and approve merges, upsert landmarks, bind taxonomy, instructions and pipeline, define and revise Datasets, create Dataset Versions, create, confirm and cancel Runs, submit and land prelabel Jobs, route and assign Tasks.
`admin`	Rename, mark and delete the project; issue and revoke rungs on it; tombstone a Dataset Version.

The dashboard names the rungs Viewer (read), Contributor (contribute), Operator (operate) and Project admin (admin). A write denied at guarded authorization answers AUTHORIZATION_DENIED naming the missing scope or rung and a decisionId. A write refused before it reaches that check, such as an unscoped request whose body is invalid, answers AUTHORIZATION_DENIED with no decisionId and records nothing. A read below the required rung is refused too, but the read check persists no Decision, so a refused read carries no decisionId and does not appear in the Decision list.

Human roles

The pipeline, not the account, names the working roles. A workflow definition declares its own roles (for example annotator, reviewer) and each stage may require one; the rung granted on the Access page decides whether a person may hold work at all, and the stage’s requiredRole and requiredQualifications decide whether this person may hold this work. The contract declares qualifications but has no dated-evidence model for them.

Working role, as a pipeline names it	What the product enforces
Annotator	Holds `contribute`; ends a Task with Submit, which writes an `annotate` commit under their principal, or a `rework` commit on a rework Task, when there are labels or answers to record.
Reviewer	Holds `contribute`; the claim refuses the authors of the revision under review (every principal with events in its commits is one), unless a coordinator holding `operate` directs the Task to them, and then the Task records the exception; verdicts bind the judged hash.
Project administrator	Holds `admin`; grants rungs, renames, marks and deletes.

Why the two tables stay separate

The role matrix answers “who may administer this account?” The rung table answers “who may act inside this project?” A workspace admin is a project admin everywhere by construction, and a plain member is nothing on a project until someone grants a rung. Merging the two would hide that a member with no grant can open no project at all.

Who can claim a stage

A rung says whether a person may act in a project. Eligibility says whether this person fits this work. A claim needs both, and it needs room: under the person’s load limit and under the stage’s limit.

Check	What passes it	Where it is set
Project rung	`contribute` or higher on the project.	The Access page’s grants.
Stage role	The role the stage requires, if it requires one.	The stage, in the pipeline. The person’s role is granted on the Access page.
Stage qualifications	Every qualification the stage requires, on the same person.	The stage, in the pipeline. The person’s qualifications are granted on the Access page.
Router geography and load	Only when the stage’s router assigns by rule: the person matches the geography it names, if any, and holds fewer Tasks than its maximum load.	The router, in the pipeline.
Stage capacity	The stage has fewer Tasks in progress than its router’s work-in-progress limit.	The router, in the pipeline.
Author exclusion	At `review` stages only: not an author of the work under review, unless a coordinator holding `operate` directs the Task to them.	Enforced; see Review and rework.

Four details decide most surprises:

Only a stage’s required role limits anyone. A workflow definition also declares a roles list, but that list restricts nobody, and a declared role that no stage requires opens nothing to anyone. A stage that requires no role passes everyone with contribute on the role check, and the other checks above still apply.
Stage roles and qualifications belong to the person across the workspace. They are granted on a project’s Access page, by a workspace owner or admin, and apply at the person’s next claim in every project of the workspace. Removing one leaves work the person already holds with them.
A model Agent holds no stage roles or qualifications, so it can work only at stages that require neither.
A Task is judged against the pipeline version it was created under. Adding or removing a requirement reaches only Tasks created after the pipeline is applied. A grant needs no new pipeline version, because the claim reads the person’s roles when it happens, but it opens waiting work only to a person who passes the other checks in the table. Pipelines explains why.

When nobody in the workspace holds a stage’s requirement, every claim there is refused, the owner’s included. The stage’s card on the Pipeline tab then says “Nobody holds it”, and the Inspector offers Grant on Access, a link to the Access page.

Machine roles

Two kinds of machine principal exist, and the ladder treats them differently.

Question	Agent credential	Hosted model Agent
Who is it?	A service account an owner or admin creates on Team settings, then Service accounts, for a script, a CI job, a service or an agent. It has an owner, and one or more tokens prove it.	A checkpoint on Nitsor’s roster (SAM 2.1 hiera large), provisioned as a principal on every workspace.
What may it do?	The account permissions its service account holds, from those its creator held; a token inherits them or is narrower. It never exercises `members:write`, `billing:write`, `clearance:write` or `service-accounts:manage`. It reaches no project until a project admin grants it a rung on the project’s Access page, and never above `operate`. A project admin can also allow its service account to tombstone Dataset Versions in one project for up to 90 days at a time; its rung stays `operate`.	Only the grant rows an admin gave it, capped at `contribute`. It never judges human-authored work.
How long does it last?	Each token lasts until it expires, 90 days after creation by default and 365 at most, or is revoked. A replacement keeps the service account and the principal. The service account lasts until it is retired: Disable pauses it, and Retire ends it for good, so none of its tokens authenticates again, and revokes the tokens that were live at that moment. A credential with no expiry is treated as expired.	Until retired. A retired Agent holds nothing while its rows stay visible for removal.
What version acted?	The credential’s `subject` is the principal on every event it writes; its `serviceAccountId` appears on the service-account creation and credential issue events; a revoke event carries the credential id and an optional reason.	The Agent Version (model version and image digest) is on every Run, Job and proposal.
Who is accountable?	Its owner, the member to ask, who does not give it its access. Create, disable, enable, retire, owner changes, and token issue and revoke are events.	The admin who granted it a rung, and the person who confirmed the Run.
How is its output treated?	As that principal’s writes; a script can annotate only where it holds `contribute`.	Proposals land in the editor marked as model-authored; a person accepts or corrects each one.
Can it approve?	No. It cannot record review verdicts, mint credentials or grant rungs.	No.

An agent credential’s token is generated with a cryptographically secure random number generator, shown once, and stored only as its SHA-256. A service account’s page lists each token with its status, and a revoked token stays listed for audit. Create one service account per job: every token of a service account acts as the same subject, so a service account shared by several tools makes the Ledger name one subject for all of them. Service accounts and tokens covers creating, rolling and revoking a token.

Provenance

Every governed write is an event on a branch with a principal, an authorization Decision and a Ledger entry. The minimum a later reader can recover:

Field	Why it exists	Who or what writes it
Principal (type, issuer, subject)	Names the actor behind the event.	The control plane, from the authenticated session or credential; never the body.
Decision (`allow` or `deny`)	Records the policy result, reason code, resource and scope a write was checked against. Read checks persist none.	The authorization seam, before the event is appended.
Ledger entry	Ties an accepted event to its Decision and principal.	The control plane, on append.
Commit parents and content root	Says which earlier state the change was made against.	The checkpoint that closed the Task.
Taxonomy version and workflow version	Fix what each label meant and how work was routed at the time.	The bindings in force, hashed into the content root.
Annotation provenance	Distinguishes a mask a person drew from one a model proposed; part of the annotation hash.	The editor or the runner.
Agent Version on a Run or Job	Names the model, its version and its image digest.	The run driver, from the image pin.
Review outcome with judged hash	Preserves the verdict and exactly what it judged.	The reviewer, as a hash-bound event.

Almost nothing is self-reported. The one field a caller supplies about itself is the idempotencyKey, and the server refuses reserved namespaces (asset-commit:, safety-checkpoint:).

Denials and failed actions

Denials at guarded write authorization are kept. Such a refusal records a deny Decision with a reason code, and the response carries its decisionId, so an investigator can read the attempt through GET /api/v1/decisions. A write the route layer refuses earlier, because the credential lacks the account scope and the body is invalid, is answered without a Decision. A refused read is not recorded. Ledger entries exist only for accepted events. Neither has a dashboard screen. Clearances are a further check. A source can carry export-control markings, and a principal reaches marked data only when the account has recorded a clearance for every marking on it. A missing clearance denies after the grant check; an agent is never eligible for clearance:write.

Next step

List the human and machine identities involved in one real workflow, then read Review and rework to define how their outcomes combine.

Plans	All plans
Last verified	2026-10-21

Get started

Concepts

Guides

Reference

Identity, role, and permission

Workspace roles

Project rungs

Human roles

Why the two tables stay separate

Who can claim a stage

Machine roles

Provenance

Denials and failed actions

Next step

​Identity, role, and permission

​Workspace roles

​Project rungs

​Human roles

​Why the two tables stay separate

​Who can claim a stage

​Machine roles

​Provenance

​Denials and failed actions

​Next step

Identity, role, and permission

Workspace roles

Project rungs

Human roles

Why the two tables stay separate

Who can claim a stage

Machine roles

Provenance

Denials and failed actions

Next step