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.

Fleet Mission Passports

Starting a fleet Mission returns a Passport derived from that Mission’s approved access. Its services identify exact connection IDs, and its fleet reference binds the token to the policy revision, membership and Mission. STACK checks those records again during execution, so a valid signature alone does not preserve revoked access.

Renewal keeps the same Mission and session. Delegation is available only when policy permits it, and the receiving agent must belong to the fleet. A child Passport retains the Mission and may narrow its parent’s access. Neither renewal nor delegation resets usage.

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 stk.services identifies a service, its permitted scopes and the connection used for the call:

• 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

Issue a Passport for an agent with the required scopes and expiry. Every Passport is issued for exactly one live Mission: open one with POST /v1/missions and pass its ID in mission_ids, or open the Mission and issue its Passport in one call with POST /v1/missions/start. A fleet agent starts an authorized Mission or issues against an existing one. The default lifetime is 15 minutes for standard and logged agents, with a maximum of one hour. An enforced agent's Passport lives for one checkpoint interval (5 minutes by default) and ignores ttl_seconds at issue. The Mission, policy and identity lease can shorten either.

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.

Checkout closes a Passport run and submits its final report for review against the recorded behavior. Complete the Mission separately when the whole job is finished.

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 and services; estimated duration is optional)
• Requires periodic checkpoints (configurable interval, 60s-3600s). The Passport TTL is the interval
• 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
• expired_no_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