Organization¶

These routes publish what the console's Organization and API Keys pages show: who is in your organization, who is invited, which API tokens exist, and what each token has done.

Route	What it serves
`GET /api/org/members`	the roster, the auto join rules, the outstanding invitations
`GET /api/org/tokens`	every API token the organization holds, as metadata
`GET /api/org/tokens/{token_id}/activity`	one token's activity trail; `self` is the calling token
`DELETE /api/org/tokens/self`	the calling token revokes itself
`GET /api/org/activity`	the organization's trail: every member's and every token's recorded write, newest first

Contract: GET /api/org/openapi.json.

Every route takes an org API token. The organization is the token's own and nothing identifies it on the wire. Any of your organization's tokens reads these routes, cluster bound or org wide. The one write is a token revoking itself. Adding or removing a member, adding a rule, minting a token, and revoking another token are console actions. Removing a member revokes every token that member minted, and retiring the organization revokes every token it holds; those revokes appear in the activity trail under the actor system:offboard.

Members and invitations¶

curl -H "Authorization: Bearer $NC_TOKEN" \
  https://nationalcompute.com/api/org/members

members[] is the roster: username, email, name, is_active (false when the identity provider has suspended the account; true means active, or unknown while the identity provider read is degraded), last_login (RFC 3339, or null), and role. Every member holds the one organization role, admin. When the identity provider read is degraded, email and name read empty and last_login reads null rather than stale.

rules[] are the auto join rules, each {id, kind, value}. A domain rule admits every sign in whose email carries that domain. An email rule invites one address. invited[] lists the email rules no member has consumed yet, the rows the console shows as Invited. An invitation counts as consumed once a member carries the email, or its username form when the identity provider read is degraded. An invitation made from the console also emails that address a one time sign in link. The link is currently valid for 3 days. A member who signs in with a Google account under that address can ignore the link.

Tokens¶

curl -H "Authorization: Bearer $NC_TOKEN" \
  https://nationalcompute.com/api/org/tokens

tokens[] lists every token, live and inactive, newest first: token_id (the middle segment of national_compute_<id>_<secret>), name, scopes as recorded at mint, cluster (the bound cluster, or null for an org wide token), expires_at, created_by, created_at, last_used_at, and revoked_at (null while live). A secret is shown once, at mint, on the console. It never appears here, and neither does its hash. The organization's kind, standard or public_research, is on GET /api/whoami as org_kind.

Activity¶

curl -H "Authorization: Bearer $NC_TOKEN" \
  https://nationalcompute.com/api/org/tokens/self/activity

The trail of one token, newest first. self is the calling token; a token_id from the token list reads any token of your organization. An id outside your organization reads 404 not-found, the same as an unknown id.

entries[] are the console audit rows the token wrote as actor. Writes are always recorded: capacity declares and swaps, limit prices, ssh key adds and revokes. The token's own mint and revoke rows are included, with the console user who performed them as actor. Two reads are recorded on every call as well, the VM capacity read and the ssh key list. Those rows stay out of the trail unless you pass reads=1. Other reads are not recorded. last_used_at on the token list says whether a token is in use.

Each entry carries id, ts (RFC 3339 UTC), actor (token:<id> for the token's own calls), action (for example vm_capacity_put, k8s_bid_put, vm_key_add, vm_token_mint, vm_token_revoke; with reads=1 also vm_capacity_get and vm_keys_get), subject (a cluster name, or the organization for key and token rows), and detail (the recorded arguments, free text).

Paging is by entry id. limit is 100 by default and clamps to 500. When more is true, pass the last entry's id as before for the next page. A limit or before that is not an integer, a before that is not positive, or a reads other than 1 or 0 reads 422 bad-request.

The console shows the same trail: the API Keys page has an Activity toggle on every token row, with a show reads switch in the panel. On the MCP server the token list and both trails are grid_api paths; self names no token there.

The organization's trail¶

curl -H "Authorization: Bearer $NC_TOKEN" \
  https://nationalcompute.com/api/org/activity

Every recorded write in your organization, newest first, human and token side by side. Three kinds of rows arrive: every write any of your tokens made, every row about the organization itself (token mint and revoke, the spend limit, the billing pages, member and rule changes), and your members' console writes on your clusters, tied to each cluster's own island. A limit price or a capacity declaration a member set on the console reads here with the member as actor, so an agent learns whose hand moved a ceiling before it acts on the change. Platform admin actions on your clusters are not included. Platform system rows about the organization are. A console row whose actor ties to no member, or whose cluster is not one of yours on its island, reads absent. Rows of another organization never appear, even from a cluster elsewhere that carries your organization's name or from a person who belongs to both organizations.

Entries carry the same fields as the token trail. Read rows hide unless reads=1. Paging is by entry id: limit is 100 by default and clamps to 500, and when more is true, pass the last entry's id as before. The response is {org_id, entries, more}.

Rate limit¶

Every token carries a budget of requests per minute across all routes (300 by default; the vm contract states the figure in force). The call past it reads 429 rate-limited with retry_after_s, and the Retry-After header carries the same figure.

Revoking your own token¶

curl -X DELETE -H "Authorization: Bearer $NC_TOKEN" \
  https://nationalcompute.com/api/org/tokens/self

The calling token stops working at once. The next call with it reads 401 unauthorized. The response is {ok, token_id, revoked_at}. The audit row carries actor token:<id>, so the trail shows the token closing itself. No token can revoke another token. That stays a console action on the API Keys page.