Autonomy, permissions, and audit

Autonomy is set per agent version and per environment, in three levels that ship today.

• Versions, not edits. Publishing creates a numbered version with a changelog; a pin moves an environment from one version to the next, and the move is an activity entry.
• Lock what must not change. An agent with read_only set answers 403 to everyone but a platform administrator.
• Start Safe. Run a routine Safe in UAT until its record shows it checked out, then set Autonomous where the risk allows.

Three roles, one permission per route. Admin holds every permission. Builder creates, edits, and runs everyday objects outside PROD. Member reads everything except secrets, machine access, members, and billing. Every route on the API reference names the permission it needs.

curl -s "$NSTACK_BASE/core/api/v1/organizations/$NSTACK_ORG/me/permissions" -H "$H"
curl -s "$NSTACK_BASE/core/api/v1/organizations/$NSTACK_ORG/permissions" -H "$H"   # the catalog

const me = await get(`${core}/me`);
const can = (perm: string) => me.permissions.includes(perm);   // strings as the catalog at …/permissions names them

if (can(PERM.readRuns)) showRunsPanel();
if (!can(PERM.manageProduction)) hideProdActions();

Check permissions before you offer an action, and expect the service to check again. A refused call answers 403 forbidden with the permission it wanted.

• Organization on every call. The path names it, the credential must belong to it, and a mismatch answers 403 org_mismatch before anything is read. Platform admins get no exception.
• Environment on everything that touches data or runs. Connection settings, knowledge indexes, pins, schedules, and machine tokens are all per environment, so DEV never reaches PROD credentials.
• Production is a second gate. A change to a PROD environment needs the permission to manage production on top of the route's own. Studio asks the member to type the environment's alias; your code should confirm too.
• Fail closed. When a service cannot confirm whether an environment is production, it refuses the change with 503 production_check_unavailable.

No call is trusted for the network it came from, and no run is trusted for the agent that started it. These are the checks in the services today.

ChecksWhat every request passes before it changes anything, drawn on a sample call.

Two records cover the platform. The run record holds everything that ran: steps, events, actor, duration, and cost. The activity feed holds every configuration change: who changed what, from which value to which, with secrets redacted. Each has its own read permission, so a team can hold one without the other.

Pick the object, filter both records by it, and keep your own copy. The same recipe works for an agent, a connection, an automation, an environment, or a person.

1. Changes to it. GET …/activity?object_type=agent_config&object_id=…. For a person, filter by actor_id instead.
2. Runs of it. GET …/runs?subject_id=…, and …/runs/{run_id}/events for any run you want in full.
3. Your copy. Export the activity range to NDJSON each night into your SIEM or object store. The lines carry the hashes.
4. Prove it. Call …/activity:verify over the exported range and keep the head_hash. A changed entry makes its fingerprint stop matching, along with every one after it.

FROM=$(date -u -v-1d +%Y-%m-%dT00:00:00Z); TO=$(date -u +%Y-%m-%dT00:00:00Z)

curl -s -X POST "$NSTACK_BASE/core/api/v1/organizations/$NSTACK_ORG/activity:export" -H "$H" \
  -H "Content-Type: application/json" -d "{\"from\":\"$FROM\",\"to\":\"$TO\"}" > "activity-$FROM.ndjson"

FIRST=$(head -1 "activity-$FROM.ndjson" | python3 -c "import sys,json; print(json.load(sys.stdin)['seq'])")
LAST=$(tail -1 "activity-$FROM.ndjson" | python3 -c "import sys,json; print(json.load(sys.stdin)['seq'])")
curl -s "$NSTACK_BASE/core/api/v1/organizations/$NSTACK_ORG/activity:verify?from_seq=$FIRST&to_seq=$LAST" -H "$H"

const lines = await (await fetch(`${core}/activity:export`, {
  method: "POST", headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ from, to }),
})).text();
await siem.put(`nstack/activity/${from}.ndjson`, lines);

const rows = lines.trim().split("\n").map((l) => JSON.parse(l));
const check = await get(`${core}/activity:verify?from_seq=${rows[0].seq}&to_seq=${rows.at(-1).seq}`);
if (!check.ok) page(ops.security, `activity chain mismatch at seq ${check.first_mismatch_seq}`);

{ "ok": true, "checked": 1842, "head_hash": "a71e…", "first_mismatch_seq": null }

• Retention settings. GET and PUT …/settings/retention hold the organization's retention settings; updating them needs the permission to update the organization.
• Deletes are soft. A connection, dataset, ontology template, or agent comes back within 30 days with POST …:restore.
• Cost settings. …/settings/economics holds the rates Scan uses to value time saved, so the numbers on …/scan/runs:stats are yours.

• In design Scopes per MCP key and OAuth 2.1 for assistants that support it.
• In design Machine access to REST, scoped by permission and environment.
• In design Approvals through the API, with decision routes and SLA timers.