DOCS / GUIDES / PASSPORT LIFECYCLE

Guide: passport lifecycle

Issue → checkpoint → checkout → review. The canonical flow for a passport inenforced or logged mode. Standard-mode agents skip checkpoints and reviews.

Every Passport is issued for exactly one Mission. POST /v1/missions/start opens the Mission and issues its first Passport in one call. The example below opens the Mission first and then issues against it. For fleet work, start the Mission with its fleet policy and use Mission renewal to continue the job.

Prerequisites

Agent registered with accountability_mode = enforced or logged
A live Mission for the agent: an authorized fleet Mission, or one you open for an independently registered agent that holds the required service grants.
Optional: identity claims attached to the operator if the services require them

1. Issue

Declare intent at issue time. Enforced and logged agents requireintent.summary andintent.services. Omitting them throwsACCOUNTABILITY_REQUIRED.

bash

# Open the Mission for the agent
curl -X POST https://api.getstack.run/v1/missions \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_support_bot",
    "intent_summary": "Answer one customer ticket and post a resolution",
    "intent_services": ["slack", "github"]
  }'
# -> { "mission_id": "ms_4hT9pQ2xVn", ... }

# Issue the Passport for that Mission
curl -X POST https://api.getstack.run/v1/passports/issue \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_support_bot",
    "mission_ids": ["ms_4hT9pQ2xVn"],
    "intent": {
      "summary": "Answer one customer ticket and post a resolution",
      "services": ["slack", "github"],
      "estimated_duration_seconds": 900,
      "will_delegate": false
    },
    "ttl_seconds": 900,
    "checkpoint_interval_seconds": 300
  }'

json

{
  "token": "eyJhbGciOi...",
  "jti": "pas_8f3a",
  "expires_at": "2026-04-23T14:47:12.000Z"
}

2. Do work through the proxy

Send each outbound call that STACK should govern through POST /v1/proxy with the Passport in the X-Passport-Token header. STACK enforces scope and constraints on calls made through that path; direct calls from the runtime bypass it.

3. Checkpoint

Submit a checkpoint before checkpoint_interval_secondselapses. In enforced mode, the checkpoint advances the stored monitoring deadline and returns new_expires_at. It does not change the signed token expiry. Refresh the Passport to receive a successor JWT. The worker emits checkpoint_silence after more than two missed intervals.

bash

curl -X POST https://api.getstack.run/v1/passports/pas_8f3a/checkpoint \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "services_used": ["slack", "github"],
    "actions_count": 3,
    "summary": "Pulled ticket context; drafting reply"
  }'

4. Check out

Passport checkout is separate from Mission completion. Checkout submits the final activity report and runs the review engine. The result is clean, flagged, or blocked. Completing a Mission does not submit this checkout.

bash

curl -X POST https://api.getstack.run/v1/passports/pas_8f3a/checkout \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "services_used": ["slack", "github"],
    "actions_count": 12,
    "summary": "Ticket resolved; PR merged; customer notified"
  }'

json

{
  "jti": "pas_8f3a",
  "checkout_status": "flagged",
  "flags": [
    { "type": "undeclared_service", "severity": "warning",
      "message": "Agent used notion but did not declare it in intent" }
  ]
}

5. Review (flagged or blocked only)

Flagged checkouts queue for an operator decision. Approval changes the checkout status to clean. A block prevents future Passport issuance until an operator unblocks the agent.

bash

# list pending reviews
curl https://api.getstack.run/v1/passports/reviews?status=flagged \
  -H "Authorization: Bearer $STACK_API_KEY"

# decide
curl -X POST https://api.getstack.run/v1/passports/reviews/cout_abc/decide \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approved", "notes": "Notion use was ancillary; accept" }'

6. Audit

Issue, checkpoint, checkout, and review decisions write to the audit chain under layer: vault with actions passport.issue,passport.checkpoint,passport.checkout,passport.review_decide. Retrieve the full trail for a jti:

bash

curl "https://api.getstack.run/v1/audit/export?from=...&to=..." \
  -H "Authorization: Bearer $STACK_API_KEY" \
  | jq '.rows[] | select(.passport_jti == "pas_8f3a")'