Identity and tokens

Humans sign in to Staff with the same org session as the main app. Actors need a platform identity when they run outside that UI: sessions on runners, schedules, and MCP clients.

The durable subject is the Staff actor. An agt_ token is an exportable credential for that actor's current permission set. Rotating or copying a token does not fork permissions. Revoke the actor or the token rows and every copy dies with them.

Two permission modes

Console: Admin → RBAC seats (/staff/rbac). There you enable RBAC on an actor, buy/adjust seat capacity (Stripe), mint a token, and revoke exports.

Minting an agt_ token

1. Confirm the actor exists and, if you need custom RBAC, that a paid seat is available and RBAC is enabled on that actor.
2. RBAC seats → mint. The token is shown once. Store it in your secret manager.
3. Use it as Authorization: Bearer agt_… against the workflow API and MCP (https://mcp.orkestia.dev/mcp).
4. Rotate by minting a new row and revoking the old one. Do not put a member Cognito JWT or a GitHub PAT in an agent runtime.

The engine ignores client-supplied organization_uuid / actor ids on start. Org and actor come from the token. That is what stops cross-org calls even if a prompt tries to pass another tenant's UUID.

MCP as the actor

Desktop IDEs, claude/codex MCP configs, and schedules should use the actor's agt_ token, not yours.

{
  "mcpServers": {
    "orkestia": {
      "url": "https://mcp.orkestia.dev/mcp",
      "headers": {
        "Authorization": "Bearer agt_…"
      }
    }
  }
}

Call whoami first. You should see actor_kind: "agent" (or equivalent) and your org. Then list_workflow_types — the catalog is already scoped.

The built-in workflow MCP on the session uses a run-scoped credential the launcher injects. You only mint agt_ when you run an MCP client or an external scheduler as that actor.

What not to do

• Do not reuse one member API token for every actor. Audit and blast radius collapse.
• Do not pass organization_uuid in initial_data unless the workflow schema requires it — and then it must match the token's org.
• Do not treat integration keys (external systems) as Staff identity. Those are a different credential family.