Admin reference

Use this when you administer a hosted Spor organization and need to invite teammates with spor invite, understand identity binding through person nodes and stewards edges, manage tokens, or find the full CLI and API references for org administration.

You do not need this if you are a non-admin member; use Hosted Spor instead. If you are looking up exact command entries, use Team administration.

After reading this, you should be able to invite a teammate with a token bound to their person node, tell whether a token has admin authority, and find the full CLI or API entry for an admin operation.

Admin is a graph fact: the admins are the people holding a stewards edge from their person node to the organization’s root node. Provider roles and email domains confer no admin authority.

The trust model is otherwise flat. A team token grants full read and write on the team graph; admin gating is the exception, not the default, and this page covers the admin-facing surfaces (a metrics export endpoint is also admin-gated — see API reads). spor whoami marks an admin token with an (admin) suffix; in the API, the same fact is the is_admin field of GET /v1/me.

Invite a teammate

spor invite mints a person-bound token and prints a paste-ready spor join line for the teammate. It is a remote-mode command and needs an admin token.

spor invite --name 'Marek Ilves' --email marek@tidefall.example.com --expires 30d

Use --person <id> to bind an existing person node, or --name and --email to create the person node first. The full command entry is in Team administration.

Good onboarding is three deliberate steps: author the person node, add their stewards edges, and mint the token bound to the node. The invite command can create the person node, but it does not replace thinking about stewardship. Skip the stewards edges and questions in that person’s area route to no one. See Identity and attribution and Ask and answer questions.

The invitee’s path is covered in I was invited to hosted Spor. The REST twin is POST /v1/admin/tokens, which mints a token bound to someone else’s person node; see Tokens and agents.

Fix an unbound identity

If a token authenticates but maps to no person node, GET /v1/me reports bound: false and the CLI warns. Routed questions and that person’s personal queue come back empty until an admin gives them a token bound to the right person node.

Use the invitation path above, or mint a person-bound token with POST /v1/admin/tokens. The admin gate for these endpoints is described in Authentication.

Manage people

Onboarding a teammate through the API is two calls: POST /v1/admin/people creates the canonical person subject first (neither a PAT mint nor a provider callback can conjure one), then POST /v1/admin/tokens binds a PAT to it. GET /v1/admin/people lists every person subject, including token counts and admin status; DELETE /v1/admin/people/{id} offboards one, revoking every PAT and OAuth grant without deleting the node itself. Full endpoint detail, including error cases, is in Tokens and agents.

Manage tokens

Everyday token management is self-serve:

spor token create
spor token list
spor token revoke <prefix>

Each member manages their own tokens. See the token CLI reference and Tokens and access for the member-facing path.

Admins get the team-wide forms:

spor admin token list
spor admin token revoke <prefix>

The equivalent commands are spor token list --all and spor token revoke <prefix> --all. The endpoints live under /v1/admin/tokens; non-admin callers get 403.

Listings show hash prefixes and metadata only. The server keeps only a hash and cannot show plaintext it never stored.

Revoking a personal access token also revokes every OAuth grant authorized with it. That cascade is the offboarding move: an admin revoking a departing member’s token also disconnects that person’s connected assistants.

Agents

Agents are person-owned and self-serve. Members create and manage their own agents; see Agents and attribution.

The admin extras are API surfaces: GET /v1/agents?all=1 lists every agent in the organization, POST /v1/admin/agents creates an agent on behalf of another person, and GET /v1/profiles/{id}/hosts shows an admin the whole host fleet where an ordinary member sees only their own boxes. Full endpoint detail is in Tokens and agents.

Run a gardener sweep

spor admin gardener runs a gardener sweep now.

spor admin gardener

The sweep files its observations as type: finding queue items and resolves its own findings whose condition has cleared. It never mutates human-authored nodes. The full verb entry, including the gating caveat, is in Team administration.

Export data

spor export --history writes a git bundle of the whole graph repository with full commit provenance. This is the data-exit path and is available to any member.

spor export --auth is the admin-gated form that also bundles the credential set for disaster restore.

See Data, privacy, and export and the export CLI reference.