---
title: "Issue an Agent Passport"
method: POST
path: "/api/passport"
tags: ["Agent Passport"]
---

# Issue an Agent Passport

`POST /api/passport`

## Request

- Base URL: `https://flint.network`
- URL: `https://flint.network/api/passport`
- Auth: none required

Issues a hybrid-signed (ES256 + ML-DSA-65) Agent Passport that binds an agent to its controller and wallet. The passport signs identity only; the mandate is a separate, unsigned, mutable config. Persists the passport, seeds the Trust Graph, and returns a public resolvable id. Free and per-IP rate limited.

## Request body

- PassportIssueRequest
  - `agent` object, required: Agent identity. Signed into the passport.
    - `agent_id` string
    - `agent_name` string
    - `controller_id` string
    - `controller_type` 'user' | 'organization'
    - `wallet_address` string
    - `attestations` object[]
    - `controller_name` string: Optional human-readable display label for the controller, signed into the passport identity right after controller_type. Distinct from controller_id: controller_id is the accountable identifier, controller_name is a display label. Null when not supplied.
  - `mandate` object: Mutable spend authority captured at issue. NOT part of the passport signature.
    - `allowed_actions` string[]
    - `max_transaction_amount` number
    - `notes` string
  - `supersede_management_token` string: Optional. The management_token (raw claim token) of a specific prior UNCLAIMED passport with the same agent_id and controller_id. Presenting it authorizes superseding that prior passport at mint even with no authenticated session, since it proves possession of that prior's own claim link. Without it, and without a session whose controller_assurance is verified or command, a remint that reuses a prior's agent_id and controller_id does not supersede that prior; the prior is left alone and reported back in related_passports with a warning instead.

## Response `200`

Passport issued.

- PassportResponse
  - `passport_id` string: kya_ prefix + ULID.
  - `flint_agent_id` string: Trust Graph node key (faid_ prefix).
  - `passport` object: Hybrid-v0 signature envelope.
    - `envelope_version` string
    - `jws` string: ES256 compact JWS over the identity-only payload.
    - `pq_signature` string, nullable: ML-DSA-65 signature (base64url).
    - `pq_kid` string, nullable
    - `pq_alg` string, nullable
  - `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.
  - `verification` object
    - `signature_valid` boolean
    - `status` string
    - `not_expired` boolean
    - `valid` boolean
  - `identity` PassportIdentity: The identity-only payload that is hybrid-signed into the passport envelope. record_version stays "1.0": controller_name and controller_assurance are additive fields, not a version bump.
    - `passport_id` string
    - `record_type` string
    - `record_version` string
    - `issuer` string
    - `issuer_key_id` string
    - `status` string
    - `issued_at` string, date-time
    - `expires_at` string, date-time
    - `agent_id` string
    - `agent_name` string, nullable
    - `controller_id` string: Who is accountable on the signed identity. Not the same as the FLINT account that owns the passport (see Ownership.owner_account_ref).
    - `controller_type` 'user' | 'organization'
    - `controller_name` string, nullable: Optional human-readable display label for the controller. Null when not supplied.
    - `controller_assurance` 'verified' | 'unverified' | 'command': "command" when FLINT Command set the controller. "verified" when the minting session's account email equals controller_id (case-insensitive), or an authenticated session's org is the controller. "unverified" otherwise, including every anonymous mint.
    - `wallet_address` string
    - `attestations` object[]
    - `core_record_hash` string
  - `mint_src` string: Sanitized mint source label.
  - `owned` boolean: Top-level mirror of ownership.owned, for cheap assertions.
  - `unclaimed` boolean: Top-level mirror of ownership.unclaimed.
  - `claim_state` 'claimed' | 'pending' | 'superseded' | 'none': Top-level mirror of ownership.claim_state.
  - `superseded_by` string, nullable: Top-level mirror of ownership.superseded_by.
  - `ownership` Ownership: Public-safe ownership and claim lifecycle state for a passport. Never includes emails or raw WorkOS user ids. Identical shape on the issue response, GET /api/passport/{passport_id}, and POST /api/account/claim.
    - `owned` boolean: True once a FLINT account holds this passport.
    - `unclaimed` boolean: The logical negation of owned.
    - `claimed_at` string, date-time, nullable: When the passport was claimed. Null while unclaimed.
    - `owner_account_ref` string, nullable: One-way account reference: "acct_" followed by the first 16 hex characters of sha256(owner user id). Never the raw WorkOS user id or email. Null while unclaimed.
    - `claim_state` 'claimed' | 'pending' | 'superseded' | 'none': "claimed": owned. "pending": unclaimed with an open claim token. "superseded": unclaimed and replaced by a remint. "none": unclaimed with no open claim (claim-token storage failed at mint, or it was consumed with no refresh).
    - `superseded_by` string, nullable: passport_id of the passport that superseded this one, when this passport was UNCLAIMED at the time of a remint with the same controller_id and agent_id. Null otherwise. A CLAIMED passport is never superseded automatically.
    - `supersedes` string[]: passport_id values this passport superseded at mint (prior unclaimed passports for the same controller_id and agent_id).
    - `protection_state` 'unprotected' | 'armed_no_channel' | 'protected' | 'frozen' | 'revoked': Sentinel protection summary: unprotected (not claimed or not armed), armed_no_channel (armed, no alert channel linked), protected (armed with a channel), frozen, or revoked.
  - `claim_url` string: One-time claim link. Present only on an anonymous (unowned) mint whose claim token was stored successfully. Absent on an owned mint.
  - `existing_claimed_passports` string[]: passport_id values for prior CLAIMED passports with the same controller_id and agent_id that a remint left alone (never superseded automatically). Present only when at least one exists.
  - `warnings` string[]: Response-level warnings, such as an existing_claimed_passports notice.
  - `mandate_warnings` string[]: Copy of mandate.mandate_warnings, surfaced at the top level for convenience.

## Other responses

- `400`: Invalid request.
- `429`: Rate limited.

---

[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)