Skip to main content
Every governed agent has its own cryptographic identity — a short-lived, signed token issued by Rubric, bound to a stable agentId. The SDK obtains and refreshes it automatically. You don’t write any of this code yourself.

​
What the identity gives you

The signed identity is a 60-minute token that the SDK presents on every call to Rubric. Two properties matter:
  • Stable agent id. Audit ingest, trace upload, and bundle reads all assert the agent id against the body of the request — an agent can only ship attribution for itself. There is no way to forge another agent’s events.
  • Auto-rotating. The SDK refreshes the token ahead of expiry. Your code never sees an auth error from a normal expiry.
The signing key is owned by Rubric. Your agents never see it.

​
How the SDK bootstraps

Enrollment is the only bootstrap path. You mint a long-lived, register-only enrollment token in the dashboard and drop it into your agent process as an environment variable. On startup the SDK presents the token plus an agentName, and Rubric mints a fresh signed identity for that agent. 
from rubric import Governance

# AG_ENROLLMENT_TOKEN and AG_AGENT_NAME from env
with Governance.bootstrap(agent_name="payments-bot") as gov:
    ...
Or the decorator API: 
import rubric

rubric.init(agent_name="payments-bot")
Properties of the enrollment flow:
  • Idempotent on agentName — the same (org, agentName) always resolves to the same agent identity. Restarts and redeploys don’t pile up identities; only the short-lived signed token rotates.
  • Register-only — a leaked enrollment token cannot ship audit events or read bundles. Worst case: an attacker creates new agent rows in your org. Bounded, auditable, revocable per-token.
  • Rate-limited — each token has a maxEnrollmentsPerHour cap (default 60). Brute-force protection.
  • Expires — 90 days by default; renewable from the dashboard with a successor token.
A brand-new enrolled agent starts with no scoped policies — the SDK gets an empty bundle until an operator adds the agent to at least one policy’s scope. See Policies for the scope model.

​
Lifecycle

1

Bootstrap

SDK reads AG_ENROLLMENT_TOKEN and AG_AGENT_NAME from env, exchanges them for a freshly-minted signed identity.
2

Auto-refresh

The SDK schedules a refresh at ~50 min into the token’s lifetime. The agent never sees an auth error from a normal expiry.
3

Revocation

Operator clicks Revoke on an identity in the dashboard. The current token keeps working until expiry (max 60 min). Refresh attempts and new enrollments for the same agentName are rejected — operator must un-revoke or rename.
4

Process exit

Governance.shutdown() (or the with block exiting) stops the refresh thread. Next process boot re-enrolls and resumes against the same identity.

​
Naming

agentName is what you pass to bootstrap(agent_name=…). Rubric normalizes it into the agent’s stable id (lowercase, dash-separated, max 128 chars). Choose names that:
  • Identify the role, not the host. payments-bot, customer-support-router — not agent-prod-us-east-1c.
  • Survive redeployment. The whole point of idempotent enrollment is that payments-bot v2 inherits v1’s identity.
  • Differ across environments. Use a suffix or a separate org per environment: payments-bot-stage vs payments-bot-prod.

​
Provenance

Every identity is stamped with the enrollment token that minted it. The Enrollment page’s per-token table shows the running count of agents enrolled, and revoking a token doesn’t kill the identities it minted — those signed tokens are independent. To kill a specific agent, revoke its identity directly.