PassportResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/flint-network/json-schema/flint-network-passport-response-schema.json",
  "title": "PassportResponse",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/flint-network-openapi.json#/components/schemas/PassportResponse",
  "type": "object",
  "properties": {
    "passport_id": {
      "type": "string",
      "description": "kya_ prefix + ULID."
    },
    "flint_agent_id": {
      "type": "string",
      "description": "Trust Graph node key (faid_ prefix)."
    },
    "passport": {
      "type": "object",
      "description": "Hybrid-v0 signature envelope.",
      "properties": {
        "envelope_version": {
          "type": "string"
        },
        "jws": {
          "type": "string",
          "description": "ES256 compact JWS over the identity-only payload."
        },
        "pq_signature": {
          "type": [
            "string",
            "null"
          ],
          "description": "ML-DSA-65 signature (base64url)."
        },
        "pq_kid": {
          "type": [
            "string",
            "null"
          ]
        },
        "pq_alg": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "mandate": {
      "$ref": "#/$defs/Mandate"
    },
    "verification": {
      "type": "object",
      "properties": {
        "signature_valid": {
          "type": "boolean"
        },
        "status": {
          "type": "string"
        },
        "not_expired": {
          "type": "boolean"
        },
        "valid": {
          "type": "boolean"
        }
      }
    },
    "identity": {
      "$ref": "#/$defs/PassportIdentity"
    },
    "mint_src": {
      "type": "string",
      "description": "Sanitized mint source label."
    },
    "owned": {
      "type": "boolean",
      "description": "Top-level mirror of ownership.owned, for cheap assertions."
    },
    "unclaimed": {
      "type": "boolean",
      "description": "Top-level mirror of ownership.unclaimed."
    },
    "claim_state": {
      "type": "string",
      "enum": [
        "claimed",
        "pending",
        "superseded",
        "none"
      ],
      "description": "Top-level mirror of ownership.claim_state."
    },
    "superseded_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "Top-level mirror of ownership.superseded_by."
    },
    "ownership": {
      "$ref": "#/$defs/Ownership"
    },
    "claim_url": {
      "type": "string",
      "description": "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": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Response-level warnings, such as an existing_claimed_passports notice."
    },
    "mandate_warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Copy of mandate.mandate_warnings, surfaced at the top level for convenience."
    }
  },
  "$defs": {
    "Mandate": {
      "type": "object",
      "description": "Unsigned, mutable mandate config read at decision time.",
      "properties": {
        "passport_id": {
          "type": "string"
        },
        "allowed_actions": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "A FLINT mandate vocabulary action. When the mandate was set with the ALL preset this is the full expanded vocabulary list, not the literal string \"ALL\"."
          }
        },
        "max_transaction_amount": {
          "type": "number"
        },
        "notes": {
          "type": [
            "string",
            "null"
          ]
        },
        "version": {
          "type": "integer"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "preset": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "ALL",
            null
          ],
          "description": "\"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": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "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."
        }
      }
    },
    "Ownership": {
      "type": "object",
      "description": "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.",
      "properties": {
        "owned": {
          "type": "boolean",
          "description": "True once a FLINT account holds this passport."
        },
        "unclaimed": {
          "type": "boolean",
          "description": "The logical negation of owned."
        },
        "claimed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the passport was claimed. Null while unclaimed."
        },
        "owner_account_ref": {
          "type": [
            "string",
            "null"
          ],
          "description": "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": {
          "type": "string",
          "enum": [
            "claimed",
            "pending",
            "superseded",
            "none"
          ],
          "description": "\"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": {
          "type": [
            "string",
            "null"
          ],
          "description": "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": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "passport_id values this passport superseded at mint (prior unclaimed passports for the same controller_id and agent_id)."
        },
        "protection_state": {
          "type": "string",
          "enum": [
            "unprotected",
            "armed_no_channel",
            "protected",
            "frozen",
            "revoked"
          ],
          "description": "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."
        }
      }
    },
    "PassportIdentity": {
      "type": "object",
      "description": "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.",
      "properties": {
        "passport_id": {
          "type": "string"
        },
        "record_type": {
          "type": "string"
        },
        "record_version": {
          "type": "string"
        },
        "issuer": {
          "type": "string"
        },
        "issuer_key_id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "issued_at": {
          "type": "string",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        },
        "agent_id": {
          "type": "string"
        },
        "agent_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "controller_id": {
          "type": "string",
          "description": "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": {
          "type": "string",
          "enum": [
            "user",
            "organization"
          ]
        },
        "controller_name": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120,
          "description": "Optional human-readable display label for the controller. Null when not supplied."
        },
        "controller_assurance": {
          "type": "string",
          "enum": [
            "verified",
            "unverified",
            "command"
          ],
          "description": "\"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": {
          "type": "string"
        },
        "attestations": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "core_record_hash": {
          "type": "string"
        }
      }
    }
  }
}