tapimo 0.4.0 → 0.4.3

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

@@ -53,11 +53,11 @@ export namespace schema {
           z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
         ),
       projectId: z.optional(z.string()).check(
-        z.describe('Owning project id (`prj_…`).'), // prettier-ignore
+        z.describe('Attributed project id (`prj_…`).'), // prettier-ignore
         z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
       ),
       scopes: z
-        .array(z.enum([...Scope.catalog.map((entry) => entry.scope), Scope.wildcard]))
+        .array(z.string().check(z.minLength(1)))
         .check(
           z.describe(
             "Granted scopes. '*' (grant-all) appears only on keys minted by the super admin.",
@@ -138,7 +138,15 @@ export namespace schema {
         .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.enum(Scope.catalog.map((entry) => entry.scope))), [])
+        ._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.'))
@@ -210,11 +218,7 @@ export namespace schema {
 }
 
 /**
- * Mounts the `/orgs/:orgId/projects/:projectId/api-keys` resource
- * (project-scoped mint/list/revoke) plus the org-wide read
- * `/orgs/:orgId/api-keys`, over the KV state store. Access follows the
- * org/project scope (owning session or super admin); the token appears once,
- * at mint.
+ * Mounts project-attributed API key mint, list, and revoke routes plus the org-wide list. Access follows the caller's organization ownership.
  */
 export function apiKeys(options: apiKeys.Options = {}) {
   const hidden = !options.enabled
@@ -233,7 +237,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
         message: 'Check the request body and try again.',
       }),
       OpenApi.describeRoute({
-        description: 'Mint a project-scoped API key. The token appears once and is never shown again.', // prettier-ignore
+        description: 'Mint a project-attributed API key. The token appears once and is never shown again.', // prettier-ignore
         hide: hidden,
         operationId: 'createApiKey',
         responses: OpenApi.responses({
@@ -273,20 +277,19 @@ export function apiKeys(options: apiKeys.Options = {}) {
 
         const body = c.req.valid('json')
 
-        // Sessions mint only self-issuable scopes; the super admin grants the
-        // full catalog. Self-serve covers the whole catalog now that billing
-        // ships, so this is a safety net: a future non-self-serve scope would
-        // be refused here without further changes.
-        if (createdBy !== 'super_admin') {
-          const denied = body.scopes.filter((scope) => !Scope.selfServe.includes(scope))
-          if (denied.length > 0)
-            return Response.error(c, {
-              code: 'scope_not_issuable',
-              message: 'The requested scopes are not issuable.',
-              status: 403,
-            })
-        }
+        if (!body.scopes.every((scope) => Scope.includes(c.get('scopeCatalog'), scope)))
+          return Response.error(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+            status: 400,
+          })
 
+        if (!canIssue(c, body.scopes))
+          return Response.error(c, {
+            code: 'scope_not_issuable',
+            message: 'The requested scopes are not issuable.',
+            status: 403,
+          })
         try {
           const orgId = Auth.org(c).id
           // Snapshot billing onto the record so the auth path throttles a
@@ -296,15 +299,19 @@ export function apiKeys(options: apiKeys.Options = {}) {
             body.environment === 'sandbox'
               ? await Billing.active(Db.get(c.get('db')), orgId, 'sandbox')
               : undefined
-          const { record, token } = await ApiKeys.mint(kv.store, {
-            createdBy,
-            environment: body.environment,
-            ...(billingActive === undefined ? {} : { billingActive }),
-            ...(body.name === undefined ? {} : { name: body.name }),
-            orgId,
-            projectId: Auth.project(c).id,
-            scopes: body.scopes,
-          })
+          const { record, token } = await ApiKeys.mint(
+            kv.store,
+            {
+              createdBy,
+              environment: body.environment,
+              ...(billingActive === undefined ? {} : { billingActive }),
+              ...(body.name === undefined ? {} : { name: body.name }),
+              orgId,
+              projectId: Auth.project(c).id,
+              scopes: body.scopes,
+            },
+            { scopeCatalog: c.get('scopeCatalog') },
+          )
           return c.json(
             Response.validated(schema.createApiKey.Response, { ...serializeKey(record), token }),
             200,
@@ -316,7 +323,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
     )
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       Auth.ensureProject(),
       OpenApi.validate('param', schema.Params, {
@@ -344,7 +351,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
         tags: ['API Keys'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -363,6 +370,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
           const records = await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
             environment: c.req.valid('query').environment,
             projectId: Auth.project(c).id,
+            scopeCatalog: c.get('scopeCatalog'),
           })
           return c.json(
             Response.validated(schema.listApiKeys.Response, {
@@ -377,7 +385,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
     )
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/api-keys',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.OrgParams, {
         code: 'param_invalid',
@@ -405,7 +413,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
         tags: ['API Keys'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -423,6 +431,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
         try {
           const records = await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
             environment: c.req.valid('query').environment,
+            scopeCatalog: c.get('scopeCatalog'),
           })
           return c.json(
             Response.validated(schema.listOrgApiKeys.Response, {
@@ -437,7 +446,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
     )
     .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({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       Auth.ensureProject(),
       OpenApi.validate('param', schema.KeyParams, {
@@ -459,7 +468,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
         tags: ['API Keys'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -473,7 +482,9 @@ export function apiKeys(options: apiKeys.Options = {}) {
         try {
           // Bind the key to the scoped project before revoking: a key id from
           // another org or project must be indistinguishable from a missing one.
-          const record = await ApiKeys.get(kv.store, keyId)
+          const record = await ApiKeys.get(kv.store, keyId, {
+            scopeCatalog: c.get('scopeCatalog'),
+          })
           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)
@@ -518,6 +529,20 @@ function mintedBy(c: Context<App.Environment>) {
   return undefined
 }
 
+/** Checks whether the caller may grant every requested scope. */
+function canIssue(c: Context<App.Environment>, scopes: readonly Scope.Id[]) {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type === 'super_admin') return true
+  if (principal?.type === 'session') {
+    const selfServe = Scope.selfServeFrom(c.get('scopeCatalog'))
+    return (
+      scopes.every((scope) => selfServe.includes(scope)) &&
+      (!scopes.includes('management:write') || Auth.membership(c)?.role === 'owner')
+    )
+  }
+  return false
+}
+
 function keyNotFound(c: Context<App.Environment>) {
   return Response.error(c, {
     code: 'api_key_not_found',

package/src/apps/management/routes/billing.ts

@@ -234,14 +234,13 @@ export namespace schema {
 }
 
 /**
- * Mounts the billing surface: an organization's billing status. Orgs without
- * a Stripe billing source read as `none`. Session lane; reads for members.
+ * Mounts billing routes. Reads require membership or scoped API key access; organizations without Stripe state return `none`.
  */
 export function billing() {
   return new Hono<Environment>()
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -264,7 +263,7 @@ export function billing() {
         tags: ['Billing'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -294,7 +293,7 @@ export function billing() {
     )
     .patch(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -325,7 +324,7 @@ export function billing() {
         tags: ['Billing'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -381,7 +380,7 @@ export function billing() {
     )
     .post(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/stripe/checkout',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -408,7 +407,7 @@ export function billing() {
         tags: ['Billing'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -466,7 +465,7 @@ export function billing() {
     )
     .post(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/stripe/manage',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -493,7 +492,7 @@ export function billing() {
         tags: ['Billing'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -529,7 +528,7 @@ export function billing() {
     )
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/payment-methods',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -555,7 +554,7 @@ export function billing() {
         tags: ['Billing'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -615,7 +614,7 @@ export function billing() {
     )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/payment-methods/:methodId{pm_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.MethodParams, {
         code: 'param_invalid',
@@ -642,7 +641,7 @@ export function billing() {
         tags: ['Billing'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -797,6 +796,7 @@ async function syncKeyBilling(
     active: options.status === 'active',
     environment: 'sandbox',
     orgId: options.orgId,
+    scopeCatalog: c.get('scopeCatalog'),
   })
 }
 

package/src/apps/management/routes/invitations.test.ts

@@ -6,6 +6,7 @@ import * as Invitations from '../../../db/tables/invitations.js'
 import * as InvitationsApp from './invitations.js'
 import * as Memberships from '../../../db/tables/memberships.js'
 import * as Orgs from './orgs.js'
+import * as Organizations from '../../../db/tables/organizations.js'
 import * as Users from '../../../db/tables/users.js'
 
 /** Origin pinned for SIWE domain binding; Hono test requests use this host. */
@@ -36,11 +37,26 @@ function sender() {
 /** Super admin secret configured on the test app. */
 const secret = 'tempo:sk:d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3'
 
-function createApp(options: { db?: ReturnType<typeof TestApp.database>; email?: App.Email } = {}) {
+/** Organization management credential used by API-key route tests. */
+const management = {
+  id: 'key_management',
+  orgId: 'org_management',
+  scopes: ['management:read', 'management:write'],
+  token: 'secret_management_key',
+} satisfies TestApp.kvStore.Key
+
+function createApp(
+  options: {
+    db?: ReturnType<typeof TestApp.database>
+    email?: App.Email
+    kv?: { store: ReturnType<typeof TestApp.kvStore> }
+  } = {},
+) {
   return TestApp.create({
     auth: { superAdmin: { secret } },
     db: options.db ?? TestApp.database(),
     ...(options.email ? { email: options.email } : {}),
+    ...(options.kv ? { kv: options.kv } : {}),
     session: { wallet: { origin } },
   })
 }
@@ -55,6 +71,47 @@ async function session(app: ReturnType<typeof createApp>) {
 }
 
 describe('invitations', () => {
+  test('lets management keys manage organization invitations', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: management.orgId, name: 'Acme' })
+    const app = createApp({
+      db,
+      kv: { store: TestApp.kvStore({ keys: [management] }) },
+    })
+    const path = `/v1/orgs/${management.orgId}/invitations`
+    const headers = {
+      'content-type': 'application/json',
+      'tempo-api-key': management.token,
+    }
+
+    const created = await app.request(path, {
+      body: JSON.stringify({ email: 'dev@example.com', role: 'owner' }),
+      headers,
+      method: 'POST',
+    })
+    expect(created.status).toBe(200)
+    const invitation = await TestApp.json(created, InvitationsApp.schema.Invitation)
+    expect(invitation.invitedBy).toBe(management.id)
+
+    const listed = await app.request(path, { headers })
+    expect(listed.status).toBe(200)
+    expect(
+      (await TestApp.json(listed, InvitationsApp.schema.listInvitations.Response)).data.map(
+        ({ id }) => id,
+      ),
+    ).toEqual([invitation.id])
+
+    expect((await app.request('/v1/invitations', { headers })).status).toBe(403)
+    expect(
+      (
+        await app.request(`${path}/${invitation.id}`, {
+          headers,
+          method: 'DELETE',
+        })
+      ).status,
+    ).toBe(200)
+  })
+
   test('invites, surfaces, and accepts into membership', async () => {
     const db = TestApp.database()
     const { email, sent } = sender()
@@ -123,6 +180,50 @@ describe('invitations', () => {
     expect(again.status).toBe(404)
   })
 
+  test('accepting an invitation preserves membership in another organization', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const invitee = await session(app)
+    const createdA = await app.request('/v1/orgs', json('POST', invitee.cookie, { name: 'Org A' }))
+    const orgA = await TestApp.json(createdA, Orgs.schema.Organization)
+    await Users.setEmail(db, invitee.userId, 'dev@example.com')
+
+    const owner = await session(app)
+    const createdB = await app.request('/v1/orgs', json('POST', owner.cookie, { name: 'Org B' }))
+    const orgB = await TestApp.json(createdB, Orgs.schema.Organization)
+    const invited = await app.request(
+      `/v1/orgs/${orgB.id}/invitations`,
+      json('POST', owner.cookie, { email: 'dev@example.com', role: 'member' }),
+    )
+    const invitation = await TestApp.json(invited, InvitationsApp.schema.Invitation)
+
+    const accepted = await app.request(`/v1/invitations/${invitation.id}/accept`, {
+      headers: { cookie: invitee.cookie },
+      method: 'POST',
+    })
+    expect(accepted.status).toBe(200)
+
+    const listed = await app.request('/v1/orgs', { headers: { cookie: invitee.cookie } })
+    const organizations = await TestApp.json(listed, Orgs.schema.listOrganizations.Response)
+    expect(
+      organizations.data
+        .map(({ id, role }) => ({ id, role }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+    ).toEqual(
+      [
+        { id: orgA.id, role: 'owner' },
+        { id: orgB.id, role: 'member' },
+      ].sort((a, b) => a.id.localeCompare(b.id)),
+    )
+
+    const [readA, readB] = await Promise.all([
+      app.request(`/v1/orgs/${orgA.id}`, { headers: { cookie: invitee.cookie } }),
+      app.request(`/v1/orgs/${orgB.id}`, { headers: { cookie: invitee.cookie } }),
+    ])
+    expect(readA.status).toBe(200)
+    expect(readB.status).toBe(200)
+  })
+
   test('accepting elevates an existing member but never demotes', async () => {
     const db = TestApp.database()
     const app = createApp({ db })

package/src/apps/management/routes/invitations.ts

@@ -48,7 +48,7 @@ export namespace schema {
       invitedBy: z
         .string()
         .check(
-          z.describe('User id (`usr_…`) that created the invitation.'),
+          z.describe('User or API key id that created the invitation.'),
           z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
         ),
       orgId: z
@@ -204,16 +204,14 @@ export namespace schema {
 
 /**
  * Mounts the invitations surface: org-scoped management
- * (`/orgs/:orgId/invitations`, admins and owners) plus the invitee's side
- * (`/invitations`, matched against the session's verified email). Invitation
- * emails dispatch through the sender the management group publishes on context
- * (`c.get('email')`), best-effort.
+ * (`/orgs/:orgId/invitations`) plus session-only invitee actions. Invitation
+ * emails dispatch through the management group's sender, best-effort.
  */
 export function invitations() {
   return new Hono<Environment>()
     .post(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/invitations',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -234,7 +232,7 @@ export function invitations() {
         tags: ['Invitations'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -248,9 +246,7 @@ export function invitations() {
           })
 
         const body = c.req.valid('json')
-        // Owners invite anyone; everyone else grants only roles strictly below
-        // their own (an admin invites members, never peers). The super admin
-        // has no membership and may grant any role.
+        // Owners, write-scoped keys, and the super admin grant any role; admins grant only members.
         const caller = Auth.membership(c)
         if (
           caller &&
@@ -262,7 +258,9 @@ export function invitations() {
             message: 'Cannot invite at or above your own role',
             status: 403,
           })
-        const invitedBy = caller?.userId ?? 'super_admin'
+        const principal = Auth.getPrincipal(c)
+        const invitedBy =
+          principal?.type === 'api_key' ? principal.id : (caller?.userId ?? 'super_admin')
 
         const db = Db.get(c.get('db'))
         try {
@@ -282,7 +280,7 @@ export function invitations() {
     )
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/invitations',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -301,7 +299,7 @@ export function invitations() {
         tags: ['Invitations'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -325,7 +323,7 @@ export function invitations() {
     )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/invitations/:invitationId{inv_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       OpenApi.validate('param', schema.InvitationParams, {
         code: 'param_invalid',
@@ -344,7 +342,7 @@ export function invitations() {
         tags: ['Invitations'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {

package/src/apps/management/routes/members.ts

@@ -113,14 +113,14 @@ export namespace schema {
 
 /**
  * Mounts the `/orgs/:orgId/members` resource: the organization's team.
- * Members read; owners change roles and remove members (any member may remove
- * themself). The last owner can never be demoted or removed.
+ * Members and read-scoped keys list. Owners and write-scoped keys manage;
+ * members may remove themselves. The last owner remains protected.
  */
 export function members() {
   return new Hono<App.Environment>()
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/members',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -139,7 +139,7 @@ export function members() {
         tags: ['Members'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -163,7 +163,7 @@ export function members() {
     )
     .patch(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/members/:userId{usr_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.MemberParams, {
         code: 'param_invalid',
@@ -190,7 +190,7 @@ export function members() {
         tags: ['Members'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -226,14 +226,14 @@ export function members() {
     )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/members/:userId{usr_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.MemberParams, {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
       OpenApi.describeRoute({
-        description: 'Remove a member. Owners remove anyone; any member removes themself. The last owner cannot be removed.', // prettier-ignore
+        description: 'Remove a member. Owners and management-write keys remove anyone; members remove themselves. The last owner stays.', // prettier-ignore
         operationId: 'removeMember',
         responses: OpenApi.responses({
           errors: {
@@ -252,7 +252,7 @@ export function members() {
         tags: ['Members'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -261,7 +261,7 @@ export function members() {
           })
 
         const { userId } = c.req.valid('param')
-        // Owners remove anyone; everyone else only themself (leaving the org).
+        // Owners and write-scoped keys remove anyone; other members only themselves.
         const caller = Auth.membership(c)
         if (caller && caller.role !== 'owner' && caller.userId !== userId)
           return Response.error(c, {