tapimo 0.11.0 → 0.13.0

package/src/apps/management/routes/api-keys.ts

@@ -12,82 +12,86 @@ import * as Billing from '../Billing.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
 import * as Scope from '../../../Scope.js'
 import * as ManagementError from '../Error.js'
 
 /** Zod schemas owned by the API-keys resource. */
 export namespace schema {
   /** One API key: metadata only — the token appears once, at mint. */
-  export const Key = Schema.describe(
-    z.object({
-      allowedIps: ApiKey.schema.AllowedIps.check(
-        z.describe(
-          'Client IP addresses and CIDR ranges allowed to use this key. An empty list means unrestricted.',
-        ),
-        z.meta({ examples: [['203.0.113.0/24', '2001:db8::1']] }),
-      ),
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the key was minted (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      createdBy: z
-        .optional(z.string())
-        .check(
-          z.describe('Identity that minted the key (`usr_…`, or `super_admin`).'),
-          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      environment: z
-        .enum(['production', 'sandbox'])
-        .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
-      expiresAt: z
-        .optional(z.string())
-        .check(
-          z.describe('When the key expires (ISO 8601). Absent for a non-expiring key.'),
-          z.meta({ examples: ['2027-01-01T00:00:00.000Z'] }),
-        ),
-      id: z
-        .string()
-        .check(
-          z.describe('Opaque key id (`key_…`).'),
-          z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      lastUsedAt: z
-        .optional(z.string())
-        .check(
-          z.describe('When the key last authenticated a request (ISO 8601).'),
-          z.meta({ examples: ['2026-07-21T12:34:56.000Z'] }),
-        ),
-      name: z
-        .optional(z.string())
-        .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
-      orgId: z
-        .string()
-        .check(
-          z.describe('Owning organization id (`org_…`).'),
-          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      projectId: z.optional(z.string()).check(
-        z.describe('Attributed project id (`prj_…`).'), // prettier-ignore
-        z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-      ),
-      scopes: z
-        .array(z.string().check(z.minLength(1)))
-        .check(
+  export const Key = OpenApi.component(
+    Schema.describe(
+      z.object({
+        allowedIps: ApiKey.schema.AllowedIps.check(
           z.describe(
-            "Granted scopes. '*' and non-self-serve scopes appear only on keys minted by the super admin.",
+            'Client IP addresses and CIDR ranges allowed to use this key. An empty list means unrestricted.',
           ),
-          z.meta({ examples: [['data:read']] }),
+          z.meta({ examples: [['203.0.113.0/24', '2001:db8::1']] }),
         ),
-      tokenLast4: z
-        .string()
-        .check(
-          z.describe('Last 4 characters of the plaintext token.'),
-          z.meta({ examples: ['a1b2'] }),
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the key was minted (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        createdBy: z
+          .optional(z.string())
+          .check(
+            z.describe('Identity that minted the key (`usr_…`, or `super_admin`).'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        environment: z
+          .enum(['production', 'sandbox'])
+          .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
+        expiresAt: z
+          .optional(z.iso.datetime())
+          .check(
+            z.describe('When the key expires (ISO 8601). Absent for a non-expiring key.'),
+            z.meta({ examples: ['2027-01-01T00:00:00.000Z'] }),
+          ),
+        id: z
+          .string()
+          .check(
+            z.describe('Opaque key id (`key_…`).'),
+            z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        lastUsedAt: z
+          .optional(z.iso.datetime())
+          .check(
+            z.describe('When the key last authenticated a request (ISO 8601).'),
+            z.meta({ examples: ['2026-07-21T12:34:56.000Z'] }),
+          ),
+        name: z
+          .optional(z.string())
+          .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
+        orgId: z
+          .string()
+          .check(
+            z.describe('Owning organization id (`org_…`).'),
+            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        projectId: z.optional(z.string()).check(
+          z.describe('Attributed project id (`prj_…`).'), // prettier-ignore
+          z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
         ),
-    }),
-    'An API key: metadata only — the token appears once, at mint.',
+        scopes: z
+          .array(z.string().check(z.minLength(1)))
+          .check(
+            z.describe(
+              "Granted scopes. '*' and non-self-serve scopes appear only on keys minted by the super admin.",
+            ),
+            z.meta({ examples: [['data:read']] }),
+          ),
+        tokenLast4: z
+          .string()
+          .check(
+            z.describe('Last 4 characters of the plaintext token.'),
+            z.meta({ examples: ['a1b2'] }),
+          ),
+      }),
+      'An API key: metadata only — the token appears once, at mint.',
+    ),
+    'ApiKey',
   )
 
   /** Path parameters addressing a project's key collection. */
@@ -144,53 +148,88 @@ export namespace schema {
     })
     .check(z.describe('Path parameters for one API key.'))
 
-  /** Request body minting a key. The wildcard scope is not issuable here. */
-  export const KeyBody = z
+  /** Path parameters addressing one organization-level API key. */
+  export const OrgKeyParams = z
     .object({
-      allowedIps: z
-        .optional(ApiKey.schema.AllowedIps)
+      keyId: z
+        .string()
         .check(
-          z.describe(
-            'Client IP addresses and CIDR ranges allowed to use the key. Omit or use an empty list for unrestricted access.',
-          ),
-          z.meta({ examples: [['203.0.113.0/24']] }),
+          z.describe('The key id (`key_…`).'),
+          z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      orgId: z
+        .string()
+        .check(
+          z.describe('The organization id (`org_…`).'),
+          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
         ),
-      environment: z
-        ._default(z.enum(['production', 'sandbox']), 'production')
-        .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
-      name: z
-        .optional(z.string().check(z.minLength(1), z.maxLength(100)))
-        .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
-      scopes: z
-        ._default(
-          z.array(
-            z.string().check(
-              z.minLength(1),
-              z.refine((scope) => scope !== Scope.wildcard),
+    })
+    .check(z.describe('Path parameters for one organization-level API key.'))
+
+  /** Request body minting a key. The wildcard scope is not issuable here. */
+  export const CreateApiKeyRequest = OpenApi.component(
+    z
+      .object({
+        allowedIps: z
+          .optional(ApiKey.schema.AllowedIps)
+          .check(
+            z.describe(
+              'Client IP addresses and CIDR ranges allowed to use the key. Omit or use an empty list for unrestricted access.',
             ),
+            z.meta({ examples: [['203.0.113.0/24']] }),
           ),
-          [],
-        )
-        .check(z.describe('Scopes to grant.'), z.meta({ examples: [['data:read']] })),
-    })
-    .check(z.describe('Fields for minting an API key.'))
+        environment: z
+          ._default(z.enum(['production', 'sandbox']), 'production')
+          .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
+        name: z
+          .optional(z.string().check(z.minLength(1), z.maxLength(100)))
+          .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
+        scopes: z
+          ._default(
+            z.array(
+              z.string().check(
+                z.minLength(1),
+                z.refine((scope) => scope !== Scope.wildcard),
+              ),
+            ),
+            [],
+          )
+          .check(z.describe('Scopes to grant.'), z.meta({ examples: [['data:read']] })),
+      })
+      .check(z.describe('Fields for minting an API key.')),
+    'CreateApiKeyRequest',
+  )
 
   /** Schemas for the createApiKey operation. */
   export namespace createApiKey {
     /** The minted key plus its one-time token. */
-    export const Response = Schema.describe(
-      z.extend(Key, {
-        token: z
-          .string()
-          .check(
-            z.describe('The plaintext token — shown once, unrecoverable afterward.'),
-            z.meta({ examples: ['tempo_sandbox:sk:…'] }),
-          ),
-      }),
-      'The minted key, including its one-time token.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.extend(Key, {
+          token: z
+            .string()
+            .check(
+              z.describe('The plaintext token — shown once, unrecoverable afterward.'),
+              z.meta({ examples: ['tempo_sandbox:sk:…'] }),
+            ),
+        }),
+        'The minted key, including its one-time token.',
+      ),
+      'CreateApiKeyResponse',
     )
   }
 
+  /** Non-paginated list of API key metadata. */
+  export const ApiKeyList = OpenApi.component(
+    Schema.describe(
+      z.object({
+        data: z.array(Key).check(z.describe('The API keys, newest first.')),
+      }),
+      'A non-paginated list of API key metadata.',
+    ),
+    'ApiKeyList',
+  )
+
   /** Schemas for the listApiKeys operation. */
   export namespace listApiKeys {
     /** Query parameters filtering a project's keys. */
@@ -199,12 +238,7 @@ export namespace schema {
       .check(z.describe("Query parameters for a project's API keys."))
 
     /** Non-paginated list of a project's keys. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Key).check(z.describe("The project's keys, newest first.")),
-      }),
-      "A non-paginated list of a project's API keys (metadata only).",
-    )
+    export const Response = ApiKeyList
   }
 
   /** Schemas for the listOrgApiKeys operation. */
@@ -215,44 +249,62 @@ export namespace schema {
       .check(z.describe("Query parameters for an organization's API keys."))
 
     /** Non-paginated list of every key in the organization. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z
-          .array(Key)
-          .check(z.describe("The organization's keys across all projects, newest first.")),
-      }),
-      "A non-paginated list of an organization's API keys (metadata only).",
-    )
+    export const Response = ApiKeyList
   }
 
   /** Schemas for the revokeApiKey operation. */
   export namespace revokeApiKey {
     /** Confirmation that the key was revoked. */
-    export const Response = z
-      .object({
-        id: z
-          .string()
-          .check(
-            z.describe('ID of the key that was revoked.'),
-            z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-      })
-      .check(z.describe('Confirmation that the key was revoked.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          id: z
+            .string()
+            .check(
+              z.describe('ID of the key that was revoked.'),
+              z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+        })
+        .check(z.describe('Confirmation that the key was revoked.')),
+      'RevokeApiKeyResponse',
+    )
+  }
+
+  /** Schemas for the rotateApiKey operation. */
+  export namespace rotateApiKey {
+    /** The replacement key plus its one-time token. */
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.extend(Key, {
+          token: z
+            .string()
+            .check(
+              z.describe('The plaintext token — shown once, unrecoverable afterward.'),
+              z.meta({ examples: ['tempo_sandbox:sk:…'] }),
+            ),
+        }),
+        'The replacement key, including its one-time token.',
+      ),
+      'RotateApiKeyResponse',
+    )
   }
 
   /** Schemas for the updateApiKey operation. */
   export namespace updateApiKey {
     /** Request body replacing or clearing a key's IP allowlist. */
-    export const Body = z
-      .object({
-        allowedIps: ApiKey.schema.AllowedIps.check(
-          z.describe(
-            'Replacement client IP/CIDR allowlist. Use an empty list for unrestricted access.',
+    export const Body = OpenApi.component(
+      z
+        .object({
+          allowedIps: ApiKey.schema.AllowedIps.check(
+            z.describe(
+              'Replacement client IP/CIDR allowlist. Use an empty list for unrestricted access.',
+            ),
+            z.meta({ examples: [['203.0.113.0/24']] }),
           ),
-          z.meta({ examples: [['203.0.113.0/24']] }),
-        ),
-      })
-      .check(z.describe("Fields for updating an API key's network access."))
+        })
+        .check(z.describe("Fields for updating an API key's network access.")),
+      'UpdateApiKeyRequest',
+    )
   }
 }
 
@@ -271,7 +323,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
-      OpenApi.validate('json', schema.KeyBody, {
+      OpenApi.validate('json', schema.CreateApiKeyRequest, {
         code: 'body_invalid',
         message: 'Check the request body and try again.',
       }),
@@ -281,11 +333,18 @@ export function apiKeys(options: apiKeys.Options = {}) {
         operationId: 'createApiKey',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: ['body_invalid', 'param_invalid'],
+              description: 'Malformed API key, invalid path, or invalid body.',
+            },
             403: {
               codes: ['scope_not_issuable'],
               description: 'The requested scopes are not issuable.',
             },
-            404: 'No accessible project was found for this id.',
+            404: {
+              codes: ['api_keys_not_enabled', 'organization_not_found', 'project_not_found'],
+              description: 'No accessible project or API key surface was found.',
+            },
           },
           success: {
             description: 'The minted key, including its one-time token.',
@@ -298,6 +357,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
       async (c) => {
         if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -379,8 +439,14 @@ export function apiKeys(options: apiKeys.Options = {}) {
         operationId: 'listApiKeys',
         responses: OpenApi.responses({
           errors: {
-            400: { codes: ['query_invalid'], description: 'Invalid query parameters.' },
-            404: 'No accessible project was found for this id.',
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, or invalid query.',
+            },
+            404: {
+              codes: ['api_keys_not_enabled', 'organization_not_found', 'project_not_found'],
+              description: 'No accessible project or API key surface was found.',
+            },
           },
           success: {
             description: "The project's keys, newest first (metadata only).",
@@ -441,8 +507,14 @@ export function apiKeys(options: apiKeys.Options = {}) {
         operationId: 'listOrgApiKeys',
         responses: OpenApi.responses({
           errors: {
-            400: { codes: ['query_invalid'], description: 'Invalid query parameters.' },
-            404: 'No accessible organization was found for this id.',
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, or invalid query.',
+            },
+            404: {
+              codes: ['api_keys_not_enabled', 'organization_not_found'],
+              description: 'No accessible organization or API key surface was found.',
+            },
           },
           success: {
             description: "The organization's keys across all projects, newest first (metadata only).", // prettier-ignore
@@ -484,6 +556,124 @@ export function apiKeys(options: apiKeys.Options = {}) {
         }
       },
     )
+    .post(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}/rotate',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'admin' }),
+      OpenApi.validate('param', schema.OrgKeyParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Create a replacement organization-level API key with the same access as an existing key. The existing key remains active until revoked.',
+        hide: hidden,
+        operationId: 'rotateOrgApiKey',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            403: {
+              codes: ['scope_not_issuable'],
+              description: 'The source key contains scopes the caller cannot rotate.',
+            },
+            404: {
+              codes: ['api_key_not_found', 'api_keys_not_enabled', 'organization_not_found'],
+              description: 'No accessible API key or API key surface was found.',
+            },
+          },
+          success: {
+            description: 'The replacement key, including its one-time token.',
+            schema: schema.rotateApiKey.Response,
+          },
+        }),
+        summary: 'Rotate organization API key',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const createdBy = mintedBy(c)
+        if (!createdBy) return ManagementError.sessionRequired(c)
+        const { keyId } = c.req.valid('param')
+        try {
+          const source = await ApiKeys.get(kv.store, keyId, {
+            scopeCatalog: c.get('scopeCatalog'),
+          })
+          if (!source || source.orgId !== Auth.org(c).id || source.projectId !== undefined)
+            return keyNotFound(c)
+          if (!canRotate(c, source.scopes))
+            return Response.error(c, {
+              code: 'scope_not_issuable',
+              message: 'The source key contains scopes the caller cannot rotate.',
+              status: 403,
+            })
+          return rotate(c, kv.store, source, createdBy)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .delete(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
+      Auth.ensureOrg({ role: 'admin' }),
+      OpenApi.validate('param', schema.OrgKeyParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Revoke an organization-level API key. Requests presenting its token stop resolving.',
+        hide: hidden,
+        operationId: 'revokeOrgApiKey',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            404: {
+              codes: ['api_key_not_found', 'api_keys_not_enabled', 'organization_not_found'],
+              description: 'No accessible API key or API key surface was found.',
+            },
+          },
+          success: {
+            description: 'Confirmation that the key was revoked.',
+            schema: schema.revokeApiKey.Response,
+          },
+        }),
+        summary: 'Revoke organization API key',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const { keyId } = c.req.valid('param')
+        try {
+          const record = await ApiKeys.get(kv.store, keyId, {
+            scopeCatalog: c.get('scopeCatalog'),
+          })
+          if (!record || record.orgId !== Auth.org(c).id || record.projectId !== undefined)
+            return keyNotFound(c)
+          return revoke(c, kv.store, keyId)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .patch(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}',
       Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
@@ -504,7 +694,19 @@ export function apiKeys(options: apiKeys.Options = {}) {
         operationId: 'updateApiKey',
         responses: OpenApi.responses({
           errors: {
-            404: 'No accessible API key was found for this id.',
+            400: {
+              codes: ['body_invalid', 'param_invalid'],
+              description: 'Malformed API key, invalid path, or invalid body.',
+            },
+            404: {
+              codes: [
+                'api_key_not_found',
+                'api_keys_not_enabled',
+                'organization_not_found',
+                'project_not_found',
+              ],
+              description: 'No accessible API key or API key surface was found.',
+            },
           },
           success: {
             description: 'The updated API key metadata.',
@@ -517,6 +719,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
       async (c) => {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -547,6 +750,78 @@ export function apiKeys(options: apiKeys.Options = {}) {
         }
       },
     )
+    .post(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}/rotate',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'admin' }),
+      Auth.ensureProject(),
+      OpenApi.validate('param', schema.KeyParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Create a replacement API key with the same access as an existing key. The existing key remains active until revoked.',
+        hide: hidden,
+        operationId: 'rotateApiKey',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            403: {
+              codes: ['scope_not_issuable'],
+              description: 'The source key contains scopes the caller cannot rotate.',
+            },
+            404: {
+              codes: [
+                'api_key_not_found',
+                'api_keys_not_enabled',
+                'organization_not_found',
+                'project_not_found',
+              ],
+              description: 'No accessible API key or API key surface was found.',
+            },
+          },
+          success: {
+            description: 'The replacement key, including its one-time token.',
+            schema: schema.rotateApiKey.Response,
+          },
+        }),
+        summary: 'Rotate API key',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const createdBy = mintedBy(c)
+        if (!createdBy) return ManagementError.sessionRequired(c)
+        const { keyId } = c.req.valid('param')
+        try {
+          const source = await ApiKeys.get(kv.store, keyId, {
+            scopeCatalog: c.get('scopeCatalog'),
+          })
+          if (!source || source.orgId !== Auth.org(c).id || source.projectId !== Auth.project(c).id)
+            return keyNotFound(c)
+          if (!canRotate(c, source.scopes))
+            return Response.error(c, {
+              code: 'scope_not_issuable',
+              message: 'The source key contains scopes the caller cannot rotate.',
+              status: 403,
+            })
+          return rotate(c, kv.store, source, createdBy)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}',
       Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
@@ -561,7 +836,18 @@ export function apiKeys(options: apiKeys.Options = {}) {
         hide: hidden,
         operationId: 'revokeApiKey',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible API key was found for this id.' },
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            404: {
+              codes: [
+                'api_key_not_found',
+                'api_keys_not_enabled',
+                'organization_not_found',
+                'project_not_found',
+              ],
+              description: 'No accessible API key or API key surface was found.',
+            },
+          },
           success: {
             description: 'Confirmation that the key was revoked.',
             schema: schema.revokeApiKey.Response,
@@ -573,6 +859,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
       async (c) => {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -590,9 +877,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
           })
           if (!record || record.orgId !== Auth.org(c).id || record.projectId !== Auth.project(c).id)
             return keyNotFound(c)
-          const revoked = await ApiKeys.revoke(kv.store, keyId)
-          if (!revoked) return keyNotFound(c)
-          return c.json(Response.validated(schema.revokeApiKey.Response, { id: keyId }), 200)
+          return revoke(c, kv.store, keyId)
         } catch (cause) {
           return Response.upstream(c, cause)
         }
@@ -663,6 +948,57 @@ function canIssue(c: Context<App.Environment>, scopes: readonly Scope.Id[]) {
   return false
 }
 
+/** Checks caller-specific restrictions that still apply when copying existing grants. */
+function canRotate(c: Context<App.Environment>, scopes: readonly Scope.Id[]) {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type === 'super_admin') return true
+  if (principal?.type !== 'session') return false
+  return (
+    (!scopes.includes('management:write') && !scopes.includes(Scope.wildcard)) ||
+    Auth.membership(c)?.role === 'owner'
+  )
+}
+
+/** Mints a replacement that preserves the source key's access and attribution. */
+async function rotate(
+  c: Context<App.Environment>,
+  store: Store.State,
+  source: ApiKeys.Record,
+  createdBy: string,
+) {
+  const billingActive =
+    source.environment === 'sandbox'
+      ? await Billing.active(Db.get(c.get('db')), source.orgId, 'sandbox')
+      : undefined
+  const { record, token } = await ApiKeys.mint(
+    store,
+    {
+      allowedIps: source.allowedIps,
+      createdBy,
+      environment: source.environment,
+      orgId: source.orgId,
+      ...(source.projectId === undefined ? {} : { projectId: source.projectId }),
+      scopes: source.scopes,
+      ...(billingActive === undefined ? {} : { billingActive }),
+      ...(source.expiresAt === undefined ? {} : { expiresAt: source.expiresAt }),
+      ...(source.name === undefined ? {} : { name: source.name }),
+      ...(source.rateLimits === undefined ? {} : { rateLimits: source.rateLimits }),
+    },
+    { scopeCatalog: c.get('scopeCatalog') },
+  )
+  return c.json(
+    Response.validated(schema.rotateApiKey.Response, { ...serializeKey(record), token }),
+    200,
+  )
+}
+
+/** Revokes an API key after its route has verified ownership. */
+async function revoke(c: Context<App.Environment>, store: Store.State, keyId: string) {
+  const revoked = await ApiKeys.revoke(store, keyId)
+  if (!revoked) return keyNotFound(c)
+  return c.json(Response.validated(schema.revokeApiKey.Response, { id: keyId }), 200)
+}
+
 function keyNotFound(c: Context<App.Environment>) {
   return Response.error(c, {
     code: 'api_key_not_found',