tapimo 0.11.0 → 0.13.0

package/src/Client.test-d.ts

@@ -3,6 +3,7 @@ import { Mpp as PublicMpp } from 'tapimo/mpp'
 import type * as z from 'zod/mini'
 
 import * as Activities from './apps/data/routes/activities.js'
+import * as ApiKeys from './apps/management/routes/api-keys.js'
 import * as Balances from './apps/data/routes/balances.js'
 import * as Billing from './apps/management/routes/billing.js'
 import * as Blocks from './apps/data/routes/blocks.js'
@@ -82,6 +83,50 @@ test('returns typed client', async () => {
 })
 
 describe('narrows responses by status', () => {
+  test('POST /v1/orgs/:orgId/projects/:projectId/api-keys/:keyId/rotate', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].projects[
+      ':projectId{prj_[A-Za-z0-9_-]+}'
+    ]['api-keys'][':keyId{key_[A-Za-z0-9_-]+}'].rotate.$post({
+      param: { keyId: 'key_test', orgId: 'org_test', projectId: 'prj_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+
+    if (res.status === 200) {
+      const json = await res.json()
+      expectTypeOf(json).toEqualTypeOf<z.output<typeof ApiKeys.schema.rotateApiKey.Response>>()
+    }
+  })
+
+  test('POST /v1/orgs/:orgId/api-keys/:keyId/rotate', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}']['api-keys'][
+      ':keyId{key_[A-Za-z0-9_-]+}'
+    ].rotate.$post({ param: { keyId: 'key_test', orgId: 'org_test' } })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+
+    if (res.status === 200) {
+      const json = await res.json()
+      expectTypeOf(json).toEqualTypeOf<z.output<typeof ApiKeys.schema.rotateApiKey.Response>>()
+    }
+  })
+
+  test('DELETE /v1/orgs/:orgId/api-keys/:keyId', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}']['api-keys'][
+      ':keyId{key_[A-Za-z0-9_-]+}'
+    ].$delete({ param: { keyId: 'key_test', orgId: 'org_test' } })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 429 | 502>()
+
+    if (res.status === 200) {
+      const json = await res.json()
+      expectTypeOf(json).toEqualTypeOf<z.output<typeof ApiKeys.schema.revokeApiKey.Response>>()
+    }
+  })
+
   test('POST /v1/mpp/validate', async () => {
     const client = Client.create()
     const res = await client.v1.mpp.validate.$post({ json: mppInput })
@@ -173,7 +218,7 @@ describe('narrows responses by status', () => {
         'apy.window': '24h',
         capability: 'deposit',
         'engine.type': 'erc4626',
-        include: 'access,apy,capabilities,token.logoUri,tvl,zone',
+        include: 'access,apy,capabilities,token.logoUri,tvl,zone,zones',
       },
     })
 
@@ -205,6 +250,8 @@ describe('narrows responses by status', () => {
       expectTypeOf(json.data[0]!.vaultAddress).toEqualTypeOf<`0x${string}`>()
       expectTypeOf(json.data[0]!.verified).toEqualTypeOf<boolean>()
       expectTypeOf(json.data[0]!.zone?.chainId).toEqualTypeOf<number | undefined>()
+      expectTypeOf(json.data[0]!.zones?.[0]?.deploymentBlock).toEqualTypeOf<number | undefined>()
+      expectTypeOf(json.data[0]!.zones?.[0]?.earnRouter).toEqualTypeOf<`0x${string}` | undefined>()
       expectTypeOf(json.meta?.valuation?.basis).toEqualTypeOf<'nominal' | undefined>()
       void json
       return
@@ -226,7 +273,10 @@ describe('narrows responses by status', () => {
   test('GET /v1/earn/vaults/verified', async () => {
     const client = Client.create()
     const res = await client.v1.earn.vaults.verified.$get({
-      query: { 'apy.window': '7d', include: 'access,apy,capabilities,token.logoUri,tvl,zone' },
+      query: {
+        'apy.window': '7d',
+        include: 'access,apy,capabilities,token.logoUri,tvl,zone,zones',
+      },
     })
 
     expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 502 | PaidAccessStatus>()
@@ -243,6 +293,7 @@ describe('narrows responses by status', () => {
       expectTypeOf(json.data[0]!.tvl).toEqualTypeOf<VaultValue | null | undefined>()
       expectTypeOf(json.data[0]!.tvl?.formatted).toEqualTypeOf<string | undefined>()
       expectTypeOf(json.data[0]!.verified).toEqualTypeOf<true>()
+      expectTypeOf(json.data[0]!.zones?.[0]?.chainId).toEqualTypeOf<number | undefined>()
       expectTypeOf(json.meta?.valuation?.source).toEqualTypeOf<string | undefined>()
       void json
       return
@@ -968,6 +1019,46 @@ describe('narrows responses by status', () => {
         void json
         return
       }
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'api_key_forbidden' | 'api_key_ip_forbidden' | 'forbidden'
+        >()
+        void json
+        return
+      }
+    }
+  })
+
+  test('DELETE /v1/orgs/:orgId', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].$delete({
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 409 | 502 | PublicAccessStatus>()
+
+    switch (res.status) {
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'api_key_forbidden' | 'api_key_ip_forbidden' | 'forbidden'
+        >()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'organization_not_found'>()
+        void json
+        return
+      }
+      case 409: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'sponsorships_unreported'>()
+        void json
+        return
+      }
     }
   })
 
@@ -1035,10 +1126,21 @@ describe('narrows responses by status', () => {
 
     expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
-    if (res.status === 200) {
-      const json = await res.json()
-      expectTypeOf(json.allowedIps).toEqualTypeOf<readonly string[]>()
-      void json
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.allowedIps).toEqualTypeOf<readonly string[]>()
+        void json
+        return
+      }
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'api_key_forbidden' | 'api_key_ip_forbidden' | 'forbidden'
+        >()
+        void json
+        return
+      }
     }
   })
 
@@ -1053,6 +1155,14 @@ describe('narrows responses by status', () => {
     expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'api_key_forbidden' | 'api_key_ip_forbidden' | 'forbidden'
+        >()
+        void json
+        return
+      }
       case 404: {
         const json = await res.json()
         expectTypeOf(json.error.code).toEqualTypeOf<
@@ -1117,6 +1227,12 @@ describe('narrows responses by status', () => {
         void json
         return
       }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'organization_not_found'>()
+        void json
+        return
+      }
     }
   })
 
@@ -1129,6 +1245,20 @@ describe('narrows responses by status', () => {
     expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 409 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'api_key_forbidden' | 'api_key_ip_forbidden' | 'forbidden'
+        >()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'member_not_found' | 'organization_not_found'>()
+        void json
+        return
+      }
       case 409: {
         const json = await res.json()
         expectTypeOf(json.error.code).toEqualTypeOf<'last_owner'>()
@@ -1138,6 +1268,87 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('DELETE /v1/orgs/:orgId/members/:userId', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].members[
+      ':userId{usr_[A-Za-z0-9_-]+}'
+    ].$delete({ param: { orgId: 'org_test', userId: 'usr_test' } })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 409 | 502 | PublicAccessStatus>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.userId).toEqualTypeOf<string>()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'member_not_found' | 'organization_not_found'>()
+        void json
+        return
+      }
+      case 409: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'last_owner'>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('POST /v1/orgs/:orgId/invitations', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].invitations.$post({
+      json: { email: 'dev@example.com', role: 'member' },
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.email).toEqualTypeOf<string>()
+        expectTypeOf(json.role).toEqualTypeOf<'admin' | 'member' | 'owner'>()
+        void json
+        return
+      }
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'api_key_forbidden' | 'api_key_ip_forbidden' | 'forbidden'
+        >()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'organization_not_found'>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('DELETE /v1/orgs/:orgId/invitations/:invitationId', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].invitations[
+      ':invitationId{inv_[A-Za-z0-9_-]+}'
+    ].$delete({ param: { invitationId: 'inv_test', orgId: 'org_test' } })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
+
+    if (res.status === 404) {
+      const json = await res.json()
+      expectTypeOf(json.error.code).toEqualTypeOf<
+        'invitation_not_found' | 'organization_not_found'
+      >()
+      void json
+    }
+  })
+
   test('POST /v1/orgs/:orgId/invite-links', async () => {
     const client = Client.create()
     const orgLinks = client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}']['invite-links']
@@ -1157,13 +1368,57 @@ describe('narrows responses by status', () => {
     >()
     expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
 
-    if (res.status === 200) {
-      const json = await res.json()
-      expectTypeOf(json.allowedEmailDomains).toEqualTypeOf<readonly string[] | null>()
-      expectTypeOf(json.allowedEmailDomains).toEqualTypeOf<
-        z.output<typeof InviteLinks.schema.InviteLink>['allowedEmailDomains']
-      >()
-      void json
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.allowedEmailDomains).toEqualTypeOf<readonly string[] | null>()
+        expectTypeOf(json.allowedEmailDomains).toEqualTypeOf<
+          z.output<typeof InviteLinks.schema.InviteLink>['allowedEmailDomains']
+        >()
+        void json
+        return
+      }
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'forbidden'>()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'organization_not_found'>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('PATCH /v1/orgs/:orgId/invite-links/:inviteLinkId', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}']['invite-links'][
+      ':inviteLinkId{iln_[A-Za-z0-9_-]+}'
+    ].$patch({
+      json: { enabled: false },
+      param: { inviteLinkId: 'iln_test', orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+
+    switch (res.status) {
+      case 403: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'forbidden'>()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'invite_link_not_found' | 'organization_not_found'
+        >()
+        void json
+        return
+      }
     }
   })
 
@@ -1500,14 +1755,18 @@ describe('narrows responses by status', () => {
       param: {
         transactionHash: '0x4845ae2098724ab26a5d89370dce5124d044be6a5acc164afc348662de67d474',
       },
-      query: { include: 'token.logoUri,token.verified' },
+      query: {
+        chainId: '4217',
+        include: 'zones,token.logoUri,token.verified',
+      },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 404 | 502 | PaidAccessStatus>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 404 | 409 | 502 | PaidAccessStatus>()
 
     switch (res.status) {
       case 200: {
         const json = await res.json()
+        expectTypeOf(json.chainId).toEqualTypeOf<number>()
         expectTypeOf(json.data[0]!.type).toEqualTypeOf<
           z.output<
             typeof Activities.schema.getTransactionActivities.Response
@@ -1550,6 +1809,13 @@ describe('narrows responses by status', () => {
         void json
         return
       }
+      case 409: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'transaction_ambiguous'>()
+        expectTypeOf(json.error.message).toEqualTypeOf<string>()
+        void json
+        return
+      }
       case 502: {
         const json = await res.json()
         expectTypeOf(json.error.code).toEqualTypeOf<'upstream_error'>()
@@ -2342,6 +2608,7 @@ describe('narrows responses by status', () => {
       amount: '1000000',
       destinationToken: '0x20c000000000000000000000b9537d11c60e8b50',
       mode: 'exactSource',
+      provider: 'stargate',
       recipient: `0x${'11'.repeat(20)}`,
       sender: `0x${'22'.repeat(20)}`,
       sourceChain: 'eip155:8453',
@@ -2604,6 +2871,30 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('QUERY /v1/exchange/quotes', async () => {
+    const client = Client.create()
+    const res = await client.v1.exchange.quotes.$query({
+      json: {
+        account: '0x1111111111111111111111111111111111111111',
+        amount: '1000000',
+        destinationToken: '0x20c000000000000000000000b9537d11c60e8b50',
+        mode: 'exactSource',
+        slippageBps: 50,
+        sourceToken: '0x20c0000000000000000000008f5425160ebe5525',
+      },
+      query: { include: 'token.logoUri,token.verified' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 404 | 502 | PaidAccessStatus>()
+    if (res.status === 200) {
+      const json = await res.json()
+      expectTypeOf(json.destinationAmount).toEqualTypeOf<ValuedTokenAmount>()
+      expectTypeOf(json.sourceAmount).toEqualTypeOf<ValuedTokenAmount>()
+      expectTypeOf(json.destinationToken.logoUri).toEqualTypeOf<string | undefined>()
+      expectTypeOf(json.sourceToken.verified).toEqualTypeOf<boolean | undefined>()
+    }
+  })
+
   test('POST /v1/exchange/quotes/execute', async () => {
     const client = Client.create()
     const res = await client.v1.exchange.quotes.execute.$post({
@@ -3292,7 +3583,10 @@ describe('narrows responses by status', () => {
     const client = Client.create()
     const res = await client.v1.addresses[':address'].activities.$get({
       param: { address: '0x0000000000000000000000000000000000000000' },
-      query: { include: 'token.logoUri,token.verified' },
+      query: {
+        chainId: '4217',
+        include: 'zones,token.logoUri,token.verified',
+      },
     })
 
     expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 502 | PaidAccessStatus>()
@@ -3300,6 +3594,7 @@ describe('narrows responses by status', () => {
     switch (res.status) {
       case 200: {
         const json = await res.json()
+        expectTypeOf(json.data[0]!.chainId).toEqualTypeOf<number | undefined>()
         expectTypeOf(json.data[0]!.type).toEqualTypeOf<
           z.output<typeof Activities.schema.getAddressActivities.Response>['data'][number]['type']
         >()

package/src/Scope.test.ts

@@ -52,3 +52,23 @@ describe('extend', () => {
     ).toThrowErrorMatchingInlineSnapshot(`[Error: Duplicate scope \`data:read\`.]`)
   })
 })
+
+describe('expandAliases', () => {
+  test('adds the current scope for a legacy Zone read scope', () => {
+    expect(
+      Scope.expandAliases(['data:read', 'zone:1424310001:read', 'zone:1424310001:write']),
+    ).toEqual([
+      'data:read',
+      'zone:1424310001:read',
+      'zone:1424310001:write',
+      'zone:1424310003:read',
+    ])
+  })
+
+  test('does not duplicate an existing current scope', () => {
+    expect(Scope.expandAliases(['zone:1424310001:read', 'zone:1424310003:read'])).toEqual([
+      'zone:1424310001:read',
+      'zone:1424310003:read',
+    ])
+  })
+})

package/src/Scope.ts

@@ -6,6 +6,8 @@
 
 import * as z from 'zod/mini'
 
+import * as Schema from './internal/Schema.js'
+
 /**
  * Wildcard scope. A key whose `scopes` contains this value satisfies every
  * required scope, so it never needs re-provisioning when new scopes are added.
@@ -154,6 +156,20 @@ export function includes(catalog: Catalog, scope: string): scope is Id {
   return schema.Zone.safeParse(scope).success || catalog.some((entry) => entry.scope === scope)
 }
 
+/** Adds current read scopes granted by legacy Zone read scopes. */
+export function expandAliases(scopes: readonly string[]): readonly string[] {
+  const aliases = new Set<string>()
+  for (const scope of scopes) {
+    const match = /^zone:([1-9]\d*):read$/.exec(scope)
+    if (!match) continue
+    const chainId = Number(match[1])
+    const resolved = Schema.resolveChainId(chainId)
+    if (resolved !== chainId) aliases.add(`zone:${resolved}:read`)
+  }
+  for (const scope of scopes) aliases.delete(scope)
+  return aliases.size ? [...scopes, ...aliases] : scopes
+}
+
 /** Returns the self-issuable identifiers in a scope catalog. */
 export function selfServeFrom(catalog: Catalog): readonly Id[] {
   return catalog

package/src/admin/apps/api-keys.test.ts

@@ -299,6 +299,81 @@ describe('DELETE /api-keys/:id', () => {
   })
 })
 
+describe('POST /api-keys/:id/rotate', () => {
+  test('mints a replacement with the source access and attribution', async () => {
+    const { client, store } = await setup()
+    const { record: source, token: sourceToken } = await core_ApiKeys.mint(store, {
+      allowedIps: ['203.0.113.0/24'],
+      billingActive: true,
+      createdBy: 'customer@example.com',
+      environment: 'sandbox',
+      expiresAt: '2100-01-01T00:00:00.000Z',
+      name: 'Privy Zones',
+      orgId: 'org_privy',
+      projectId: 'prj_privy',
+      rateLimits: { '*': { limit: 10_000, period: 'minute' } },
+      scopes: ['zone:421700001:read', 'zone:421700001:write'],
+    })
+
+    const response = await client['api-keys'][':id'].rotate.$post({
+      param: { id: source.id },
+    })
+    const body = await TestApp.json(response, ApiKeys.schema.rotateApiKey.Response)
+
+    expect(response.status).toBe(200)
+    expect(body).toMatchObject({
+      allowedIps: source.allowedIps,
+      billingActive: source.billingActive,
+      createdBy: TestAdmin.identity.email,
+      environment: source.environment,
+      expiresAt: source.expiresAt,
+      name: source.name,
+      orgId: source.orgId,
+      projectId: source.projectId,
+      rateLimits: source.rateLimits,
+      scopes: source.scopes,
+    })
+    expect(body.id).not.toBe(source.id)
+    expect(body.token).not.toBe(sourceToken)
+    expect(await core_ApiKeys.resolve(store, sourceToken)).not.toBeNull()
+    expect(await core_ApiKeys.resolve(store, body.token)).toMatchObject({
+      id: body.id,
+      scopes: source.scopes,
+    })
+  })
+
+  test('unknown id → 404', async () => {
+    const { client } = await setup()
+    const response = await client['api-keys'][':id'].rotate.$post({
+      param: { id: 'key_missing' },
+    })
+
+    expect(response.status).toMatchInlineSnapshot(`404`)
+  })
+
+  test('keeps a rotated one-off key assignable to an organization', async () => {
+    const { client, db, store } = await setup()
+    const organization = await Organizations.create(db, { name: 'Tempo' })
+    const { record: source } = await core_ApiKeys.mint(store, {
+      name: 'One-off',
+      scopes: ['data:read'],
+    })
+
+    const rotateResponse = await client['api-keys'][':id'].rotate.$post({
+      param: { id: source.id },
+    })
+    const replacement = await TestApp.json(rotateResponse, ApiKeys.schema.rotateApiKey.Response)
+    expect(replacement.orgId).toBe(replacement.id)
+
+    const updateResponse = await client['api-keys'][':id'].$patch({
+      json: { orgId: organization.id },
+      param: { id: replacement.id },
+    })
+    expect(updateResponse.status).toBe(200)
+    expect((await core_ApiKeys.get(store, replacement.id))?.orgId).toBe(organization.id)
+  })
+})
+
 describe('PATCH /api-keys/:id', () => {
   test('preserves the allowlist when omitted', async () => {
     const { client, store } = TestAdmin.setup()

package/src/admin/apps/api-keys.ts

@@ -173,6 +173,24 @@ export namespace schema {
       .object({ id: z.string().check(z.describe('Revoked key id.')) })
       .check(z.describe('API-key revocation result.'))
   }
+
+  /** Schemas for the rotateApiKey operation. */
+  export namespace rotateApiKey {
+    /** Path parameters for rotating a key. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.describe('Stable id of the key to rotate.'),
+            z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for rotating an API key.'))
+
+    /** Response: the replacement record plus its one-time plaintext token. */
+    export const Response = createApiKey.Response
+  }
 }
 
 /**
@@ -183,6 +201,7 @@ export namespace schema {
  * - `GET /` lists key records (metadata only), optionally filtered by `orgId`.
  * - `DELETE /:id` revokes a key by id (`404` if absent).
  * - `PATCH /:id` updates a key's allowlist, name, or project, or assigns its first organization.
+ * - `POST /:id/rotate` mints a replacement with the source key's access and attribution.
  * - `POST /backfill` rebuilds the id and org index entries for every record.
  */
 export function apiKeys() {
@@ -315,6 +334,51 @@ export function apiKeys() {
         return c.json(Response.validated(schema.revokeApiKey.Response, { id }))
       },
     )
+    .post(
+      '/:id/rotate',
+      OpenApi.validate('param', schema.rotateApiKey.Params, {
+        code: 'param_invalid',
+        message: 'Invalid path parameters',
+      }),
+      OpenApi.describeRoute({
+        description: 'Create a replacement that preserves the source key access and attribution. The source key remains active.', // prettier-ignore
+        operationId: 'rotateAdminApiKey',
+        responses: OpenApi.responses({
+          errors: { 404: 'API key not found.' },
+          success: {
+            description: 'Replacement key (includes the one-time token).',
+            schema: schema.rotateApiKey.Response,
+          },
+        }),
+        summary: 'Rotate API key',
+        tags: ['API keys'],
+      }),
+      async (c) => {
+        const { id } = c.req.valid('param')
+        const store = c.get('kv').store
+        const source = await ApiKeys.get(store, id)
+        if (!source)
+          return Response.error(c, {
+            code: 'not_found',
+            message: 'API key not found.',
+            status: 404,
+          })
+
+        const { record, token } = await ApiKeys.mint(store, {
+          allowedIps: source.allowedIps,
+          createdBy: c.get('identity')!.email,
+          environment: source.environment,
+          scopes: source.scopes,
+          ...(source.billingActive === undefined ? {} : { billingActive: source.billingActive }),
+          ...(source.expiresAt === undefined ? {} : { expiresAt: source.expiresAt }),
+          ...(source.name === undefined ? {} : { name: source.name }),
+          ...(source.orgId === source.id ? {} : { orgId: source.orgId }),
+          ...(source.projectId === undefined ? {} : { projectId: source.projectId }),
+          ...(source.rateLimits === undefined ? {} : { rateLimits: source.rateLimits }),
+        })
+        return c.json(Response.validated(schema.rotateApiKey.Response, { ...record, token }), 200)
+      },
+    )
     .patch(
       '/:id',
       OpenApi.validate('param', schema.updateApiKey.Params, {