---
title: "Update a mandate, manage a claim, or authorize a Shopify purchase"
method: POST
path: "/api/passport/{passport_id}"
tags: ["Agent Passport"]
---

# Update a mandate, manage a claim, or authorize a Shopify purchase

`POST /api/passport/{passport_id}`

## Request

- Base URL: `https://flint.network`
- URL: `https://flint.network/api/passport/{passport_id}`
- Auth: one of:
  - none
  - API key in cookie `flint_session`

Dispatches on the request body's action field (default update_mandate when omitted): update_mandate (mutable mandate config), begin_claim (validate a claim token and open a pending claim), refresh_claim_token (rotate a lost or consumed claim token), issue_purchase_authorization, or issue_preflight_capability. Updating the mandate is a pure data update: it bumps the mandate version and signs nothing, so the passport signature is unchanged.

## Path parameters

- `passport_id` string, required

## Request body

- union
  - MandateUpdateRequest
    - `action` 'update_mandate'
    - `allowed_actions` string[]
    - `max_transaction_amount` number
    - `notes` string
    - `management_token` string: Required to update the mandate of an UNCLAIMED passport: the raw claim token, presented as a management capability. Not needed once the passport is claimed; the owner's session (WorkOSOwnerSession cookie or bearerAgentSession) is used instead.
  - BeginClaimRequest
    - `action` 'begin_claim', required
    - `claim_token` string, required: The one-time claim token from the mint's claim_url.
  - RefreshClaimTokenRequest
    - `action` 'refresh_claim_token', required
    - `management_token` string: The current raw claim token, even one about to be superseded. Optional when the caller's session (WorkOSOwnerSession cookie or bearerAgentSession) already began this passport's claim, or minted it.
  - PurchaseAuthorizationRequest
    - `action` 'issue_purchase_authorization', required
    - `shop` string, required
    - `currency` string, required
    - `max_amount` number, required

## Response `200`

Mandate updated (signature unchanged), or a claim step (begin_claim / refresh_claim_token) completed.

- union
  - MandateUpdateResponse
    - `ok` boolean
    - `passport_id` string
    - `mandate` Mandate: Unsigned, mutable mandate config read at decision time.
      - `passport_id` string
      - `allowed_actions` string[]
      - `max_transaction_amount` number
      - `notes` string, nullable
      - `version` integer
      - `updated_at` string, date-time
      - `preset` 'ALL' | 'null', nullable: "ALL" when allowed_actions was set via the ALL preset (or its legacy alias all_commerce_v1) and was expanded server-side to the full vocabulary. Null when allowed_actions was set explicitly.
      - `mandate_warnings` string[]: One warning per allowed_actions entry that is not in the FLINT mandate vocabulary and is not the ALL preset. The action is kept (backward compatible) but will not match actionPermitted until it is added to the vocabulary or aliased.
    - `passport_signature_unchanged` boolean: Always true: a mandate update never re-signs the passport.
  - BeginClaimResponse
    - `ok` boolean
    - `claim_state` 'pending'
    - `passport_id` string
  - RefreshClaimTokenResponse
    - `ok` boolean
    - `passport_id` string
    - `claim_url` string: New one-time claim link. The old link stops working.
    - `claim_token` string: New raw claim token, equal to management_token.
    - `management_token` string
    - `claim_state` 'pending'
    - `refreshed_at` string, date-time

## Other responses

- `201`: Purchase authorization issued.
- `400`: Invalid request, such as a missing claim_token on begin_claim.
- `403`: claim_token_invalid (begin_claim with a wrong or expired token), refresh_not_authorized (refresh_claim_token with neither a valid management_token nor an authorized session), or the mandate-update owner/claim-token checks.
- `404`: passport_not_found, or no_pending_claim (begin_claim / refresh_claim_token with no open claim to act on).
- `409`: passport_already_owned (begin_claim / refresh_claim_token on a passport that is already claimed), passport_revoked, or passport_frozen.
- `410`: passport_superseded: this passport was replaced by a remint while it was still unclaimed. superseded_by names the replacement.
- `429`: Too many refresh_claim_token requests.

---

[API](https://skmtc.dev/flint/apis/flint-agent-transaction-control-api.md) · [All operations](https://skmtc.dev/flint/apis/flint-agent-transaction-control-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flint/apis/flint-agent-transaction-control-api/revisions/eb5052b7b5dc?raw)