docs: publish AgentID owner permission contract

[shalim786]

Summary

Follow-up to agentmail-to/agentmail-api#715 and the GA gate in plans/AGENTID_OWNER_EMAIL.md.

• add dedicated Fern request and response models for the owner_profile and owner_email permissions on AgentID public-key credentials
• expose permission selection on public-key registration and permission updates on the existing PATCH route
• document inheritance, delegation ceilings, explicit response booleans, per-field PATCH merge semantics, and immediate revocation behavior
• add the two owner permissions to the bearer API-key contract and permissions reference
• update the public-key guide and changelog examples

Why

The merged API now accepts owner permissions when public-key credentials are created or updated and always returns both permission booleans. The published Fern contract still described permissions as server-owned and immutable, so generated clients could not exercise the deployed API safely.

SDK compatibility

The TypeScript SDK has already shipped the generated updatePublicKeyName method. This PR intentionally keeps the Fern endpoint key and generated method name stable while expanding its request to update the name, owner permissions, or both. That avoids deleting an already-released method.

Developer impact

Generated Python and TypeScript clients can independently allow or block owner_profile and owner_email at credential creation and through the existing update method. Public-key responses expose both booleans explicitly, and bearer-key permission models expose the delegation ceiling used by public-key creation and update.

Root cause

The original public-key docs contract landed before the owner-scope permission storage and management paths in API PR 2a. PR 3 activated those scopes, leaving the Fern schema one delivery step behind the runtime contract.

Validation

• Fern Check CI: passed
• docs preview: passed
• OpenAPI generation and API changelog diff: passed
• TypeScript: tsc --noEmit --typeRoots /Users/shabs/Dev/agentmail/agentmail-docs/node_modules/@types
• YAML parse: all fern/**/*.yml files load successfully with Ruby Psych
• git diff --check
• compatibility inspection against released agentmail-node 0.5.18 confirms updatePublicKeyName is already public and remains stable

[github-actions]

🌿 Preview your docs: https://agentmail-preview-57bf0fbb-6908-4993-95f9-e6fb15e0a361.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/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


### POST /v0/api-keys
-  added the new optional request property `permissions/owner_email`
-  added the new optional request property `permissions/owner_profile`
-  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


### GET /v0/api-keys/public-keys
-  added the required property `public_keys/items/permissions` to the response with the `200` status


### POST /v0/api-keys/public-keys
-  added the new optional request property `permissions`
-  added the required property `permissions` to the response with the `200` status


### PATCH /v0/api-keys/public-keys/{api_key_id}
-  added the new optional request property `permissions`
-  the request property `name` became nullable
-  the request property `name` became optional
-  added the required property `permissions` to the response with the `200` status


### GET /v0/inboxes/{inbox_id}/api-keys
-  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


### POST /v0/inboxes/{inbox_id}/api-keys
-  added the new optional request property `permissions/owner_email`
-  added the new optional request property `permissions/owner_profile`
-  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


### GET /v0/pods/{pod_id}/api-keys
-  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


### POST /v0/pods/{pod_id}/api-keys
-  added the new optional request property `permissions/owner_email`
-  added the new optional request property `permissions/owner_profile`
-  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

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