---
title: Agent Passport
description: A signed, verifiable, portable statement of who an agent is and what it may do — and why it is never the authorization decision.
label: Agent Passport
---

A passport is a signed snapshot of an agent: its identity, its organization, its
capabilities, its trust evidence and its lifecycle state, with a version number
and an expiry, signed by the Veefore platform key.

It exists so an agent can present identity to something that is not Veefore —
another organization's agent, a partner system, an auditor — and have that claim
independently verified against a published key.

## What is in one

```json
{
  "passport_version": 4,
  "agent": {
    "id": "agt_01JAV7YQ4T2K9M3E8H6R5N1XZ0",
    "name": "finance-agent",
    "status": "ACTIVE",
    "verification_status": "VERIFIED"
  },
  "organization": { "id": "org_01JAV…", "name": "Acme Payments" },
  "environment": { "id": "env_01JAV…", "type": "PRODUCTION" },
  "capabilities": ["refund.create", "order.read"],
  "protocols": ["HTTP", "MCP"],
  "trust": {
    "identity_verified": true,
    "organization_verified": true,
    "security_attestation_valid": true,
    "protocol_compliance_valid": false
  },
  "key": { "id": "key_8f2c…", "algorithm": "Ed25519", "public_key": "MCowBQYDK2Vw…" },
  "issued_at": "2026-10-03T09:00:00.000Z",
  "expires_at": "2026-11-02T09:00:00.000Z",
  "signature": "…"
}
```

No secrets. The public key is in there; the private key is not, has never been,
and the passport would be useless as a portable document if it were.

## The important caveat

:::security A passport is identity, not authorization
The gateway does **not** authorize a request by reading its passport. On every
single action it re-resolves live authority from the database: the agent's
current lifecycle state, its current capability grants, the current delegation
chain, the currently active policy version, and the risk and trust state as of
now.

A passport is a snapshot and snapshots go stale. If Veefore trusted one, then
revoking an agent would not take effect until its passport expired — which
could be thirty days. Instead revocation is instant and the passport becomes a
document that fails verification.
:::

This is the distinction people most often get wrong, so it is worth stating
positively: use a passport to answer *"who is this?"*. Use the gateway to answer
*"may they do this?"*.

## Issuing and versioning

Passports are versioned. Issuing a new one supersedes the previous version
rather than editing it, so there is a history of what the agent looked like at
each point.

```bash
curl -X POST https://veefore.example.com/v1/passports/agt_01ABC/issue \
  -H "Authorization: Bearer $VEEFORE_API_KEY"
```

The default lifetime is `PASSPORT_TTL_SECONDS`, 30 days. Short enough that a
stale passport is not useful for long; long enough that reissuing is not a
constant chore. Material changes to the agent — a new capability, a lifecycle
transition, new trust evidence — are the trigger to reissue.

## Verifying one

Three different situations, three endpoints.

**You hold a passport Veefore issued and want to know if it is still good.**

```http
POST /v1/passports/{agentId}/verify
```

Checks the signature *and* compares the contents against live state. A passport
that verifies cryptographically but describes a now-revoked agent fails here,
which is the useful answer.

**Someone else presents a passport to you.**

```http
POST /v1/passports/verify-external
```

Verifies the signature against the issuer's published platform key. It tells you
the document is authentic and unaltered. It cannot tell you the remote agent is
currently in good standing — only the issuer knows that.

**You need to hand the passport to a third party.**

```http
GET /v1/passports/{agentId}/export
```

Returns the passport together with the platform verification key, so the
recipient can verify offline without calling you.

The verification key is also published, unauthenticated:

```bash
curl -s https://gateway.veefore.example.com/.well-known/veefore-platform-key
```

That response carries the key, its id, and the gateway's `audience`.

## Where passports are actually used

**A2A.** This is the main one. When you register an A2A connection you register
the remote party's expected key, and `POST /v1/a2a/connections/{id}/verify`
checks their passport against it. The connection stays `PENDING` and unusable
until it verifies. See [A2A](/build/a2a).

**Onboarding a partner.** Exporting a passport is a cleaner way to say "this
agent is ours, here is proof" than an email.

**Audit.** Having the exact passport version that was current at the time of an
action makes a six-month-old decision reconstructable.

## Signing

Ed25519, with the platform key configured as `VEEFORE_SIGNING_PRIVATE_KEY` and
identified by `VEEFORE_SIGNING_KEY_ID`. The payload is canonicalised before
signing — keys sorted, no insignificant whitespace — so two systems that
serialise JSON differently still produce the same bytes and the same signature.

:::warning Rotating the platform signing key invalidates issued passports
Every passport signed with the old key stops verifying. Plan a rotation: issue
new passports for active agents, let partners pick up the new published key,
then retire the old one. This is not a casual change.
:::

## Related

:::cards

:::card Agent identity | /concepts/identity
The key pair underneath the passport.
:::

:::card Trust evidence | /concepts/trust
What populates the `trust` block, and how policy uses it.
:::

:::card A2A | /build/a2a
Passport verification in the one place it is load-bearing.
:::

:::card Passport API | /reference/api/passport
Issue, read, export, verify, verify-external.
:::

:::