Passports

A Passport is a signed JWT that carries an agent's identity, scopes, and authorization chain. STACK-governed service calls verify this authority before execution.

Properties

• Verifiable -- any service can verify the signature and expiry without calling STACK
• Composable -- claims stack independently (identity + service access + delegation)
• Portable -- works across any service that understands the standard
• Delegatable -- human -> operator -> agent -> sub-agent, narrow-only scope, max 4 hops
• Auditable -- STACK-governed use can be linked to the Passport and its delegation chain
• Revocable -- the next STACK-verified call rejects a revoked Passport
• Graduated trust -- base level, then higher tiers via verified identity claims

JWT Structure

Passports use a stk namespace for all STACK-specific claims. The standard JWT fields (jti, sub,iss, exp) follow the RFC 7519 spec.

{
  "jti": "ppt_abc123",
  "sub": "agt_xyz",
  "iss": "https://api.getstack.run",
  "exp": 1712345678,
  "stk": {
    "operator_id": "op_...",
    "agent_id": "agt_...",
    "agent_name": "research-agent",
    "services": [
      {
        "service_id": "svc_slack",
        "service_name": "slack",
        "scopes": ["channels:read", "chat:write"],
        "credential_ref": "cred_ref_abc",
        "connection_id": "scon_a1b2c3d4"
      }
    ],
    "identity_claims": [
      {
        "claim_id": "clm_a1b2c3",
        "provider": "identity_provider",
        "layer": "humanity",
        "claim_type": "verified_human",
        "assurance_level": "high",
        "verified_at": 1712340000,
        "expires_at": 1743876000
      }
    ],
    "authority_refs": [
      {
        "binding_id": "abn_...",
        "binding_version": 1,
        "binding_claim_id": "pc_...",
        "binding_digest": "sha256:...",
        "receiver_id": "rcv_...",
        "receiver_profile_version_id": "apv_...",
        "expires_at": 1712345400
      }
    ],
    "delegation_depth": 0,
    "session_id": "ses_...",
    "accountability": "enforced",
    "intent_summary": "Summarize Q1 earnings and post to Slack",
    "intent_services": ["slack"],
    "checkpoint_interval": 300
  }
}

Services Array

Each entry in the stk.services array is a structured object with four fields:

• service_id -- the underlying service definition ID (e.g. svc_slack)
• service_name -- human-readable provider name (e.g. "slack", "github")
• scopes -- array of granted scopes for this service
• credential_ref -- KMS key reference for the encrypted credential (never the credential itself)
• connection_id -- the operator's service-connection ID (scon_*) used for freshness checks at verify time

Identity Claims

The stk.identity_claims array carries claim references and verification metadata. It excludes raw identity attributes such as name, date of birth, address, and document number. Treat the remaining provider and claim metadata as potentially sensitive.

• claim_id -- reference to the stored identity claim
• provider -- the provider key (e.g. "bankid_se", "stripe_identity")
• layer -- trust layer: "humanity", "identity", or "delegation"
• claim_type -- e.g. "verified_human", "verified_identity", "delegated_authority"
• assurance_level -- "low", "substantial", or "high"
• verified_at -- Unix timestamp of when the claim was verified
• expires_at -- Unix timestamp of claim expiry

Authority References

When issue selects authority_binding_ids, the Passport carries up to eight immutable stk.authority_refs. Each reference pins a binding version and digest, receiver profile, and expiry. It contains no principal name, proof material, mandate text, disclosed fact, or action parameter. See Authority.

Lifecycle

1. Issue -- operator issues a passport for an agent with scopes and TTL (default 15 min, max 1 hour). Optionally declare an intent (summary of what the agent will do, which services it will use).

2. Checkpoint -- agent periodically reports what it's doing: services used, actions taken, delegations made. In enforced mode, a checkpoint advances the stored monitoring deadline. It does not change the signed JWT expiry; refresh returns a new signed Passport.

3. Checkout -- agent finishes its mission and submits a final report. This triggers the review engine which compares the declared intent against actual behavior.

4. Review -- if anomalies are detected (undeclared services, excessive actions, missed checkpoints), the checkout is flagged for operator review. The operator can approve or block the agent.

Accountability Modes

Every agent has an accountability mode that controls how strictly its passport sessions are monitored. This is set at agent registration and can be updated later.

Enforced

The strictest mode. Agents must declare intent when issuing a passport, submit checkpoints at regular intervals, and checkout when done. The review engine compares actual behavior against declared intent and flags anomalies. Security signals can block credential access and prevent future passport issuance.

• Requires intent declaration (summary + services + estimated duration)
• Requires periodic checkpoints (configurable interval, 60s-3600s)
• Checkout triggers automated review with flag detection
• Anomalies generate review flags with severity levels (info, warning, critical)
• On warning/critical: configurable escalation action (notify or block)

Logged

A balanced mode. Security signals are recorded in the audit log and review flags are generated, but they do not block the agent. Checkpoints and checkout are optional but recommended. Use this mode when you want observability without enforcement.

Standard

Minimal tracking. No intent required, no checkpoints expected, no automated review. STACK still records calls that cross its runtime boundary, but it does not run the checkpoint and checkout review flow.

Checkpoint Flow

Checkpoints are progress reports submitted by an agent during an active mission. They serve two purposes: advancing the stored monitoring deadline in enforced mode and recording structured progress.

// POST /v1/passports/:jti/checkpoint
{
  "services_used": ["slack", "github"],
  "actions_count": 12,
  "summary": "Read 5 Slack channels, created 2 GitHub issues",
  "delegated_to": [],
  "tool_calls": [
    { "service": "slack", "method": "conversations.history", "target": "#engineering" },
    { "service": "github", "method": "issues.create", "target": "org/repo" }
  ]
}

When the agent completes its work, it submits a checkout report. In enforced mode, this triggers the review engine which analyzes the full session (intent, checkpoints, checkout) and generates flags for any anomalies.

// POST /v1/passports/:jti/checkout
{
  "services_used": ["slack", "github"],
  "actions_count": 25,
  "summary": "Completed Q1 analysis. Read Slack channels, created summary issues in GitHub.",
  "delegated_to": []
}

Review Flags

The review engine generates flags when it detects anomalies between declared intent and actual behavior. Each flag has a type, severity, and message.

• undeclared_service -- agent used a service not listed in its intent
• undeclared_delegation -- agent delegated to another agent without declaring it
• duration_exceeded -- mission took longer than the estimated duration
• no_checkpoints -- enforced agent never submitted a checkpoint
• checkpoint_gap -- too much time between checkpoints
• high_action_volume -- unusually high number of actions for the declared intent
• missed_checkout -- passport expired without a checkout
• credential_outside_scope -- agent accessed credentials beyond its declared scope
• credential_burst -- rapid credential access suggesting automated exfiltration
• scope_escalation_pattern -- pattern suggesting scope widening attempt