docs: align Visa SDK contract with deployed API

[shalim786]

The canonical Fern definitions lag the Visa-enabled production API: generated clients cannot express Ed25519/secp256k1 registration, client_id retries, granular public-key permissions, suspended inbox state, or versioned list replacement.

This draft aligns those non-overlapping schemas with deployed behavior:

• add strict P-256, secp256k1, and Ed25519 public JWK variants;
• add public-key client_id, current response metadata, granular permissions, and permission PATCH;
• expose message_reply, public_key_register, owner/provider, and pod-update permissions;
• add active/inactive/suspended inbox status to create, update, and response types;
• add organization/pod atomic list PUT with nullable initial version, CAS conflict, 500-entry limit, and explicit inbox-scope exclusion.

Envelope event documentation remains in #236. Removed revoke-all documentation remains in #237. The inactive portion of lifecycle overlaps #230, and owner-claim documentation overlaps the older pre-restructure #195; those PRs should be incorporated or reconciled before this leaves draft.

Validation:

• fern check --warnings: 0 errors; 25 existing warnings (24 route-pattern warnings and one unauthenticated redirect check)
• YAML parse: passed for all three changed definitions
• git diff --check: passed

Local Python/TypeScript generation is pending because Fern generation requires an authenticated Fern token on this host.

[github-actions]

🌿 Preview your docs: https://agentmail-preview-3a068895-6c94-430d-8556-8dc9bff43bcd.docs.buildwithfern.com

[github-actions]

📋 View the side-by-side API change review

The link expires in 7 days.

🔒 Your API specs are encrypted in CI before they're uploaded. The decryption key stays in this link's URL fragment (after the #), which browsers never send to a server, so oasdiff cannot read your specs. How it works →

_{Posted automatically by the oasdiff GitHub Action. To turn this off (no spec upload, no comment), set review: false on the action.}

[github-actions]

✨ API Changes

# API Changelog n/a vs. n/a


## API Changes

### GET /v0/api-keys
-  added the optional property `api_keys/items/permissions/message_reply` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/owner_email` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/owner_profile` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/pod_update` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/provider_connect` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/provider_owner_share` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/public_key_register` to the response with the `200` status


### POST /v0/api-keys
-  added the new optional request property `permissions/message_reply`
-  added the new optional request property `permissions/owner_email`
-  added the new optional request property `permissions/owner_profile`
-  added the new optional request property `permissions/pod_update`
-  added the new optional request property `permissions/provider_connect`
-  added the new optional request property `permissions/provider_owner_share`
-  added the new optional request property `permissions/public_key_register`
-  added the optional property `permissions/message_reply` to the response with the `200` status
-  added the optional property `permissions/owner_email` to the response with the `200` status
-  added the optional property `permissions/owner_profile` to the response with the `200` status
-  added the optional property `permissions/pod_update` to the response with the `200` status
-  added the optional property `permissions/provider_connect` to the response with the `200` status
-  added the optional property `permissions/provider_owner_share` to the response with the `200` status
-  added the optional property `permissions/public_key_register` to the response with the `200` status


### GET /v0/api-keys/public-keys
- :warning: added `#/components/schemas/P256PublicJwk, #/components/schemas/Secp256k1PublicJwk, #/components/schemas/Ed25519PublicJwk` to the `public_keys/items/public_key/jwk` response property `oneOf` list for the response status `200`
-  added the optional property `public_keys/items/client_id` to the response with the `200` status
-  added the optional property `public_keys/items/inbox_id` to the response with the `200` status
-  added the optional property `public_keys/items/pod_id` to the response with the `200` status
-  added the optional property `public_keys/items/used_at` to the response with the `200` status
-  removed the optional property `public_keys/items/revoked_at` from the response with the `200` status
-  added the required property `public_keys/items/allowed_scopes` to the response with the `200` status
-  added the required property `public_keys/items/created_by` to the response with the `200` status
-  added the required property `public_keys/items/organization_id` to the response with the `200` status
-  added the required property `public_keys/items/permissions` to the response with the `200` status


### POST /v0/api-keys/public-keys
- :warning: added `#/components/schemas/P256PublicJwk, #/components/schemas/Secp256k1PublicJwk, #/components/schemas/Ed25519PublicJwk` to the `public_key/jwk` response property `oneOf` list for the response status `200`
-  added the new optional request property `client_id`
-  added the new optional request property `permissions`
-  added `#/components/schemas/P256PublicJwk, #/components/schemas/Secp256k1PublicJwk, #/components/schemas/Ed25519PublicJwk` to the `public_key` request property `oneOf` list
-  added the optional property `client_id` to the response with the `200` status
-  added the optional property `inbox_id` to the response with the `200` status
-  added the optional property `pod_id` to the response with the `200` status
-  added the optional property `used_at` to the response with the `200` status
-  removed the optional property `revoked_at` from the response with the `200` status
-  added the required property `allowed_scopes` to the response with the `200` status
-  added the required property `created_by` to the response with the `200` status
-  added the required property `organization_id` to the response with the `200` status
-  added the required property `permissions` to the response with the `200` status


### PATCH /v0/api-keys/public-keys/{api_key_id}
- :warning: added `#/components/schemas/P256PublicJwk, #/components/schemas/Secp256k1PublicJwk, #/components/schemas/Ed25519PublicJwk` to the `public_key/jwk` response property `oneOf` list for the response status `200`
-  added the new optional request property `permissions`
-  the request property `name` became nullable
-  the request property `name` became optional
-  added the optional property `client_id` to the response with the `200` status
-  added the optional property `inbox_id` to the response with the `200` status
-  added the optional property `pod_id` to the response with the `200` status
-  added the optional property `used_at` to the response with the `200` status
-  removed the optional property `revoked_at` from the response with the `200` status
-  added the required property `allowed_scopes` to the response with the `200` status
-  added the required property `created_by` to the response with the `200` status
-  added the required property `organization_id` to the response with the `200` status
-  added the required property `permissions` to the response with the `200` status


### GET /v0/inboxes
-  added the optional property `inboxes/items/status` to the response with the `200` status


### POST /v0/inboxes
-  added the new optional request property `status`
-  added the optional property `status` to the response with the `200` status


### GET /v0/inboxes/search
-  added the optional property `inboxes/items/status` to the response with the `200` status


### GET /v0/inboxes/{inbox_id}
-  added the optional property `status` to the response with the `200` status


### PATCH /v0/inboxes/{inbox_id}
-  added the new optional request property `status`
-  added the optional property `status` to the response with the `200` status


### GET /v0/inboxes/{inbox_id}/api-keys
-  added the optional property `api_keys/items/permissions/message_reply` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/owner_email` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/owner_profile` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/pod_update` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/provider_connect` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/provider_owner_share` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/public_key_register` to the response with the `200` status


### POST /v0/inboxes/{inbox_id}/api-keys
-  added the new optional request property `permissions/message_reply`
-  added the new optional request property `permissions/owner_email`
-  added the new optional request property `permissions/owner_profile`
-  added the new optional request property `permissions/pod_update`
-  added the new optional request property `permissions/provider_connect`
-  added the new optional request property `permissions/provider_owner_share`
-  added the new optional request property `permissions/public_key_register`
-  added the optional property `permissions/message_reply` to the response with the `200` status
-  added the optional property `permissions/owner_email` to the response with the `200` status
-  added the optional property `permissions/owner_profile` to the response with the `200` status
-  added the optional property `permissions/pod_update` to the response with the `200` status
-  added the optional property `permissions/provider_connect` to the response with the `200` status
-  added the optional property `permissions/provider_owner_share` to the response with the `200` status
-  added the optional property `permissions/public_key_register` to the response with the `200` status


### PUT /v0/lists/{direction}/{type}
-  endpoint added


### GET /v0/pods/{pod_id}/api-keys
-  added the optional property `api_keys/items/permissions/message_reply` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/owner_email` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/owner_profile` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/pod_update` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/provider_connect` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/provider_owner_share` to the response with the `200` status
-  added the optional property `api_keys/items/permissions/public_key_register` to the response with the `200` status


### POST /v0/pods/{pod_id}/api-keys
-  added the new optional request property `permissions/message_reply`
-  added the new optional request property `permissions/owner_email`
-  added the new optional request property `permissions/owner_profile`
-  added the new optional request property `permissions/pod_update`
-  added the new optional request property `permissions/provider_connect`
-  added the new optional request property `permissions/provider_owner_share`
-  added the new optional request property `permissions/public_key_register`
-  added the optional property `permissions/message_reply` to the response with the `200` status
-  added the optional property `permissions/owner_email` to the response with the `200` status
-  added the optional property `permissions/owner_profile` to the response with the `200` status
-  added the optional property `permissions/pod_update` to the response with the `200` status
-  added the optional property `permissions/provider_connect` to the response with the `200` status
-  added the optional property `permissions/provider_owner_share` to the response with the `200` status
-  added the optional property `permissions/public_key_register` to the response with the `200` status


### GET /v0/pods/{pod_id}/inboxes
-  added the optional property `inboxes/items/status` to the response with the `200` status


### POST /v0/pods/{pod_id}/inboxes
-  added the new optional request property `status`
-  added the optional property `status` to the response with the `200` status


### GET /v0/pods/{pod_id}/inboxes/search
-  added the optional property `inboxes/items/status` to the response with the `200` status


### GET /v0/pods/{pod_id}/inboxes/{inbox_id}
-  added the optional property `status` to the response with the `200` status


### PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}
-  added the new optional request property `status`
-  added the optional property `status` to the response with the `200` status

💡 Download api-changelog-diff artifact or tag @fern Writer in #github-prs for changelog.