Authentication and tokens

An access token lets a script, agent, or CI consumer act against neosource over the API, git-over-HTTPS, or the container registry without a browser session. Every token is fine-grained and expiring by default: it carries a set of scopes and an optional resource restriction, and it can only ever do less than the account that created it.

What a token is

A token is an attenuated bearer credential. Authorization for a token-backed request is the intersection of the two:

effective = account-permissions ∩ token-grant

The account’s normal access — workspace role, repo visibility, and per-repo grants — sets the ceiling; the token’s grant narrows it. A token can never widen its owner’s access, and a leaked token exposes only the slice of authority you granted it, only until it expires.

Tokens are stored hashed at rest. The plaintext you copy once at creation has the shape prefix_payload_checksum (a CRC32 check segment, GitHub-style, so secret scanners can validate a leaked candidate offline). The prefix tells you where a token came from:

prefix	kind
`nsp_`	personal access token — owned by your account
`nso_`	workspace / org access token — owned by a service account
`nsc_`	CI job token — minted automatically per job, not by you

Creating a personal token

Create tokens in the web UI at /settings/developer, which offers a scope picker, a resource picker (workspaces / repos), and an expiry choice. The same page manages your SSH keys.

Creating or rotating a token is a sensitive action, so it requires a fresh (sudo) session — a token can never mint another token.

Scopes

Scopes are drawn from neosource’s hierarchical permission grammar; picking a parent scope covers its children. The v1 grantable catalog:

scope	covers
`repo:read`	read repo metadata + `git fetch` / clone
`repo:write`	the above + `repo:write` + `git push`
`repo:admin` (a.k.a. `repo:*`)	the above + repo settings, grants, webhooks
`workspace:read`	list a workspace’s repos + read its settings
`workspace:*`	full workspace administration
`team:read` / `team:write`	read / manage teams
`user:read` / `user:write`	profile, SSH-key list/manage, notifications
`site:admin`	the site-admin surface via a token (the account must also be a site admin)
`*`	everything the owner can do

Grant the narrowest set that gets the job done — an agent that only pushes to one repo wants repo:write on that repo, not *.

Resource restriction

Leaving the resource picker empty makes the token unrestricted — it can reach any workspace or repo its owner can, within the granted scopes. Selecting specific workspaces or repos locks the token to them: a request against anything outside the list is denied before the scope check even runs.

Expiry

Every token expires. The choices are 30 / 90 / 180 / 365 days (default 90), with a hard cap of 400 days — there is deliberately no “never”. A short-lived credential is the whole point of handing one to an automated process.

Rotating & revoking

Rotate issues a new secret for the same token — the token id, scopes, resources, and label stay put, but the old secret dies immediately. Rotation is sudo-gated and cannot be performed by the token itself, so a leaked token can’t quietly extend its own life. Update the consumer with the new secret.

Revoke kills a token outright. Revocation and rotation take effect within seconds across all nodes.

Workspace (organization) tokens

Organizations need keys that aren’t tied to any one person’s account — CI for an org repo, a shared deploy bot, an import job. A workspace token is owned by a service account: an identity that has no password and can never log in, holding a membership in the workspace at a role no higher than the creator’s and a token resource-locked to that workspace.

Create one under Organization settings → Tokens. The minted secret carries the nso_ prefix. Because the service account is a normal workspace member under the hood, the token flows through the same authz, membership, and audit machinery as a human’s access — it just can’t exceed the workspace, its role, or its scopes.

CI job tokens

Tokens with the nsc_ prefix are minted automatically for each workflow job and scoped to that job’s repo for its lifetime. They are a separate mechanism from personal and workspace tokens — you don’t create or manage them, and this page’s create/rotate flows don’t apply to them.