Checkpoints

A checkpoint is a structured progress report for an enforced or logged Passport. For enforced-mode agents, the initial signed Passport TTL uses the checkpoint interval. A successful checkpoint records progress and advances the stored monitoring deadline. It does not change the signed JWT expiry. Logged-mode checkpoints record progress without a monitoring-deadline update. Standard mode does not accept checkpoints.

Shape

{
  "services_used":  ["slack", "github"],
  "actions_count":  3,
  "delegated_to":   ["agt_notion_writer"],
  "summary":        "Pulled ticket context; drafted reply"
}

• services_used - every service hit since the last checkpoint
• actions_count - integer, number of discrete operations
• delegated_to - optional, agent IDs the parent delegated to in this window
• summary - free text, max 1000 chars

Interval presets

Set at issue time via checkpoint_interval_seconds. Choose from presets or a custom value (60s min, 3600s max).

• frequent - 2 minutes (high-risk, real-money paths)
• standard - 5 minutes (default)
• relaxed - 15 minutes (longer missions with lower stakes)
• marathon - 60 minutes (batch jobs)

TTL tying in enforced mode

In enforced mode, issue uses the checkpoint interval as the signed Passport TTL, capped at one hour. A checkpoint updates the database expiry and returns new_expires_at. It does not issue a successor JWT and cannot change the exp inside the existing token. Refresh the Passport to get a new signed token before the current token expires.

issue:       signed exp = now + interval
checkpoint:  stored new_expires_at = checkpoint time + interval
token:       signed exp is unchanged
continue:    refresh to receive a new signed Passport

Catching undeclared services

When a checkpoint reports a service outside the Passport intent, the checkpoint response includes a flag. The checkpoint does not create an immediate credential_outside_scope security event. Passport checkout later evaluates the final service report.

Endpoint

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"
  }'

Related

• /docs/guides/enforced-mode - full enforced-mode walkthrough
• /docs/guides/passport-lifecycle - issue → checkpoint → checkout → review
• /docs/concepts/detectors - checkpoint_silence and post-hoc review flag catalog