Add Update API Key endpoint documentation

[josephfeleke]

Documents the merged Update API Key endpoint and syncs the existing definition to the current API surface.

What changed in this PR

• Permission list synced with code: added message_delete; removed thread_read and thread_delete (these were replaced by message_* permissions in the API back in March/April but the docs lagged).
• Update endpoint documented with explicit semantics for the permissions field (omit / null / populated object).
• Create endpoint docstring clarified along the same lines for consistency.
• ForbiddenError (403) added to Create and Update — surfaces when a caller tries to clear permissions or grant fields they don't themselves hold.
• "At least one of name or permissions" note added on Update.

A note on null in the TypeScript SDK

The API accepts permissions: null to clear restrictions and make a key unrestricted. This is reflected in the docstring on the field. Two relevant facts about how the SDKs render this:

• Python SDK: native — permissions=None works idiomatically because Fern emits typing.Optional[ApiKeyPermissions] (which is T | None).
• TypeScript SDK: the generated type is permissions?: ApiKeyPermissions (i.e. T | undefined). Fern's YAML grammar doesn't express "nullable" — optional<T> is the closest construct, and it doesn't include null in the resulting TS type.

Net effect for TS users wanting to clear permissions: the runtime sends null correctly when given null, but the compiler will complain unless they cast ({ permissions: null as any }). The docstring on the field tells them what to send, so this is a typing limitation, not a behavior limitation. Same shape as every other update endpoint in the SDK; not unique to this PR.

If we later want first-class TS ergonomics on the clear path, the cleanest fix is an API change (replace the null semantic with a sentinel field like clear_permissions: true). That's out of scope here.

Test plan

• npx fern-api check — all checks pass.
• Permission list verified 1:1 against permissionShape in src/schemas/api-key.ts.
• Errors verified against handler throws (ForbiddenError, NotFoundError, ValidationError).
• Permission semantics docstring traced branch-by-branch against resolveCreateApiKeyPermissions and resolveUpdateApiKeyPermissions.
• Fern CI generates updated TS + Python SDKs on merge.

[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/api_key_update' to the response with the '200' status


### POST /v0/api-keys
-  added the new optional request property 'permissions/api_key_update'
-  added the optional property 'permissions/api_key_update' to the response with the '200' status


### PATCH /v0/api-keys/{api_key_id}
-  endpoint added


### GET /v0/inboxes/{inbox_id}/api-keys
-  added the optional property 'api_keys/items/permissions/api_key_update' to the response with the '200' status


### POST /v0/inboxes/{inbox_id}/api-keys
-  added the new optional request property 'permissions/api_key_update'
-  added the optional property 'permissions/api_key_update' to the response with the '200' status


### PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id}
-  endpoint added


### GET /v0/pods/{pod_id}/api-keys
-  added the optional property 'api_keys/items/permissions/api_key_update' to the response with the '200' status


### POST /v0/pods/{pod_id}/api-keys
-  added the new optional request property 'permissions/api_key_update'
-  added the optional property 'permissions/api_key_update' to the response with the '200' status


### PATCH /v0/pods/{pod_id}/api-keys/{api_key_id}
-  endpoint added

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

[github-actions]

🌿 Preview your docs: https://agentmail-preview-bae394dc-a918-43a6-8f6b-b896b5a7485e.docs.buildwithfern.com

[cubic-dev-ai]

No issues found across 3 files

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="fern/definition/api-keys.yml">

<violation number="1" location="fern/definition/api-keys.yml:244">
P2: `ForbiddenError` is missing from the `create` and `update` endpoints in the pod-scoped and inbox-scoped API key files (`fern/definition/pods/api-keys.yml`, `fern/definition/inboxes/api-keys.yml`). Both scopes share the same request types whose docs describe 403 responses for permission escalation, so their error lists should be consistent with the org scope.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

P2: ForbiddenError is missing from the create and update endpoints in the pod-scoped and inbox-scoped API key files (fern/definition/pods/api-keys.yml, fern/definition/inboxes/api-keys.yml). Both scopes share the same request types whose docs describe 403 responses for permission escalation, so their error lists should be consistent with the org scope.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At fern/definition/api-keys.yml, line 244:

<comment>`ForbiddenError` is missing from the `create` and `update` endpoints in the pod-scoped and inbox-scoped API key files (`fern/definition/pods/api-keys.yml`, `fern/definition/inboxes/api-keys.yml`). Both scopes share the same request types whose docs describe 403 responses for permission escalation, so their error lists should be consistent with the org scope.</comment>

<file context>
@@ -210,6 +241,7 @@ service:
       response: CreateApiKeyResponse
       errors:
         - global.ValidationError
+        - ForbiddenError
 
     update:
</file context>