@grantjs/schema 1.22.1 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grantjs/schema",
-  "version": "1.22.1",
+  "version": "1.23.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/events/event-catalog.ts

@@ -154,6 +154,7 @@ export const EVENT_TYPES = [
   'project.user_email_changed',
   'project.user_password_set',
   'api_key.deleted',
+  'api_key.updated',
   'tag.created',
   'tag.updated',
   'tag.deleted',
@@ -232,6 +233,7 @@ export const EVENT_CATALOG: Readonly<Record<EventType, EventCatalogEntry>> = {
   // Every project-credential write that changes the stored hash, any source. data.after = { projectId, userId, source }: never a hash or a password.
   'project.user_password_set': webhookOnly('membership'),
   'api_key.deleted': webhookOnly('security'),
+  'api_key.updated': webhookOnly('security'),
   'tag.created': webhookOnly('iam'),
   'tag.updated': webhookOnly('iam'),
   'tag.deleted': webhookOnly('iam'),

package/src/generated/graphql.ts

@@ -50,6 +50,51 @@ export type ExchangeApiKeyMutationVariables = Exact<{
 
 export type ExchangeApiKeyMutation = { exchangeApiKey: { accessToken: string; expiresIn: number } };
 
+export type GetApiKeyAttachableGrantsQueryVariables = Exact<{
+  scope: Types.Scope;
+}>;
+
+export type GetApiKeyAttachableGrantsQuery = {
+  apiKeyAttachableGrants: {
+    permissions: Array<{
+      machineOnly: boolean;
+      permission: {
+        id: string;
+        name: string;
+        action: string;
+        description: string | null;
+        resource: { id: string; slug: string; name: string } | null;
+      };
+    }>;
+    roles: Array<{ id: string; name: string; description: string | null }>;
+  };
+};
+
+export type GetApiKeyRolePermissionsQueryVariables = Exact<{
+  scope: Types.Scope;
+  ids?: Array<string | number> | string | number | null | undefined;
+}>;
+
+export type GetApiKeyRolePermissionsQuery = {
+  roles: {
+    roles: Array<{
+      id: string;
+      name: string;
+      groups: Array<{
+        id: string;
+        permissions: Array<{
+          id: string;
+          name: string;
+          action: string;
+          description: string | null;
+          resource: { id: string; slug: string; name: string } | null;
+        }> | null;
+      }> | null;
+      rolePermissions: Array<{ id: string; permissionId: string }> | null;
+    }>;
+  };
+};
+
 export type GetApiKeysQueryVariables = Exact<{
   scope: Types.Scope;
   page?: number | null | undefined;
@@ -78,6 +123,13 @@ export type GetApiKeysQuery = {
       updatedAt: Date;
       deletedAt: Date | null;
       role: { id: string; name: string } | null;
+      permissions: Array<{
+        id: string;
+        name: string;
+        action: string;
+        description: string | null;
+        resource: { id: string; slug: string; name: string } | null;
+      }> | null;
       createdByUser: { id: string; name: string; pictureUrl: string | null } | null;
       revokedByUser: { id: string; name: string; pictureUrl: string | null } | null;
     }>;
@@ -122,6 +174,31 @@ export type RotateApiKeyMutation = {
   };
 };
 
+export type SetApiKeyPermissionsMutationVariables = Exact<{
+  input: Types.SetApiKeyPermissionsInput;
+}>;
+
+export type SetApiKeyPermissionsMutation = {
+  setApiKeyPermissions: {
+    id: string;
+    clientId: string;
+    name: string | null;
+    description: string | null;
+    expiresAt: Date | null;
+    lastUsedAt: Date | null;
+    isRevoked: boolean;
+    updatedAt: Date;
+    role: { id: string; name: string } | null;
+    permissions: Array<{
+      id: string;
+      name: string;
+      action: string;
+      description: string | null;
+      resource: { id: string; slug: string; name: string } | null;
+    }> | null;
+  };
+};
+
 export type AuthSignupPolicyQueryVariables = Exact<{ [key: string]: never }>;
 
 export type AuthSignupPolicyQuery = {
@@ -2530,6 +2607,221 @@ export const ExchangeApiKeyDocument = {
     },
   ],
 } as unknown as DocumentNode<ExchangeApiKeyMutation, ExchangeApiKeyMutationVariables>;
+export const GetApiKeyAttachableGrantsDocument = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'query',
+      name: { kind: 'Name', value: 'GetApiKeyAttachableGrants' },
+      variableDefinitions: [
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+          type: {
+            kind: 'NonNullType',
+            type: { kind: 'NamedType', name: { kind: 'Name', value: 'Scope' } },
+          },
+        },
+      ],
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [
+          {
+            kind: 'Field',
+            name: { kind: 'Name', value: 'apiKeyAttachableGrants' },
+            arguments: [
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'scope' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+              },
+            ],
+            selectionSet: {
+              kind: 'SelectionSet',
+              selections: [
+                {
+                  kind: 'Field',
+                  name: { kind: 'Name', value: 'permissions' },
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      { kind: 'Field', name: { kind: 'Name', value: 'machineOnly' } },
+                      {
+                        kind: 'Field',
+                        name: { kind: 'Name', value: 'permission' },
+                        selectionSet: {
+                          kind: 'SelectionSet',
+                          selections: [
+                            { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'action' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'description' } },
+                            {
+                              kind: 'Field',
+                              name: { kind: 'Name', value: 'resource' },
+                              selectionSet: {
+                                kind: 'SelectionSet',
+                                selections: [
+                                  { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                                  { kind: 'Field', name: { kind: 'Name', value: 'slug' } },
+                                  { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                                ],
+                              },
+                            },
+                          ],
+                        },
+                      },
+                    ],
+                  },
+                },
+                {
+                  kind: 'Field',
+                  name: { kind: 'Name', value: 'roles' },
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'description' } },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  ],
+} as unknown as DocumentNode<
+  GetApiKeyAttachableGrantsQuery,
+  GetApiKeyAttachableGrantsQueryVariables
+>;
+export const GetApiKeyRolePermissionsDocument = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'query',
+      name: { kind: 'Name', value: 'GetApiKeyRolePermissions' },
+      variableDefinitions: [
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+          type: {
+            kind: 'NonNullType',
+            type: { kind: 'NamedType', name: { kind: 'Name', value: 'Scope' } },
+          },
+        },
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'ids' } },
+          type: {
+            kind: 'ListType',
+            type: {
+              kind: 'NonNullType',
+              type: { kind: 'NamedType', name: { kind: 'Name', value: 'ID' } },
+            },
+          },
+        },
+      ],
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [
+          {
+            kind: 'Field',
+            name: { kind: 'Name', value: 'roles' },
+            arguments: [
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'scope' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+              },
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'ids' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'ids' } },
+              },
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'limit' },
+                value: { kind: 'IntValue', value: '1' },
+              },
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'page' },
+                value: { kind: 'IntValue', value: '1' },
+              },
+            ],
+            selectionSet: {
+              kind: 'SelectionSet',
+              selections: [
+                {
+                  kind: 'Field',
+                  name: { kind: 'Name', value: 'roles' },
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                      {
+                        kind: 'Field',
+                        name: { kind: 'Name', value: 'groups' },
+                        selectionSet: {
+                          kind: 'SelectionSet',
+                          selections: [
+                            { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                            {
+                              kind: 'Field',
+                              name: { kind: 'Name', value: 'permissions' },
+                              selectionSet: {
+                                kind: 'SelectionSet',
+                                selections: [
+                                  { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                                  { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                                  { kind: 'Field', name: { kind: 'Name', value: 'action' } },
+                                  { kind: 'Field', name: { kind: 'Name', value: 'description' } },
+                                  {
+                                    kind: 'Field',
+                                    name: { kind: 'Name', value: 'resource' },
+                                    selectionSet: {
+                                      kind: 'SelectionSet',
+                                      selections: [
+                                        { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                                        { kind: 'Field', name: { kind: 'Name', value: 'slug' } },
+                                        { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                                      ],
+                                    },
+                                  },
+                                ],
+                              },
+                            },
+                          ],
+                        },
+                      },
+                      {
+                        kind: 'Field',
+                        name: { kind: 'Name', value: 'rolePermissions' },
+                        selectionSet: {
+                          kind: 'SelectionSet',
+                          selections: [
+                            { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'permissionId' } },
+                          ],
+                        },
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  ],
+} as unknown as DocumentNode<GetApiKeyRolePermissionsQuery, GetApiKeyRolePermissionsQueryVariables>;
 export const GetApiKeysDocument = {
   kind: 'Document',
   definitions: [
@@ -2649,6 +2941,31 @@ export const GetApiKeysDocument = {
                           ],
                         },
                       },
+                      {
+                        kind: 'Field',
+                        name: { kind: 'Name', value: 'permissions' },
+                        selectionSet: {
+                          kind: 'SelectionSet',
+                          selections: [
+                            { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'action' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'description' } },
+                            {
+                              kind: 'Field',
+                              name: { kind: 'Name', value: 'resource' },
+                              selectionSet: {
+                                kind: 'SelectionSet',
+                                selections: [
+                                  { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                                  { kind: 'Field', name: { kind: 'Name', value: 'slug' } },
+                                  { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                                ],
+                              },
+                            },
+                          ],
+                        },
+                      },
                       {
                         kind: 'Field',
                         name: { kind: 'Name', value: 'createdByUser' },
@@ -2788,6 +3105,91 @@ export const RotateApiKeyDocument = {
     },
   ],
 } as unknown as DocumentNode<RotateApiKeyMutation, RotateApiKeyMutationVariables>;
+export const SetApiKeyPermissionsDocument = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'mutation',
+      name: { kind: 'Name', value: 'SetApiKeyPermissions' },
+      variableDefinitions: [
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'input' } },
+          type: {
+            kind: 'NonNullType',
+            type: { kind: 'NamedType', name: { kind: 'Name', value: 'SetApiKeyPermissionsInput' } },
+          },
+        },
+      ],
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [
+          {
+            kind: 'Field',
+            name: { kind: 'Name', value: 'setApiKeyPermissions' },
+            arguments: [
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'input' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'input' } },
+              },
+            ],
+            selectionSet: {
+              kind: 'SelectionSet',
+              selections: [
+                { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'clientId' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'description' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'expiresAt' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'lastUsedAt' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'isRevoked' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'updatedAt' } },
+                {
+                  kind: 'Field',
+                  name: { kind: 'Name', value: 'role' },
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                    ],
+                  },
+                },
+                {
+                  kind: 'Field',
+                  name: { kind: 'Name', value: 'permissions' },
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'action' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'description' } },
+                      {
+                        kind: 'Field',
+                        name: { kind: 'Name', value: 'resource' },
+                        selectionSet: {
+                          kind: 'SelectionSet',
+                          selections: [
+                            { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'slug' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                          ],
+                        },
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  ],
+} as unknown as DocumentNode<SetApiKeyPermissionsMutation, SetApiKeyPermissionsMutationVariables>;
 export const AuthSignupPolicyDocument = {
   kind: 'Document',
   definitions: [

package/src/generated/resolvers.ts

@@ -219,6 +219,8 @@ export type ResolversTypes = ResolversObject<{
   AddUserRoleInput: Types.AddUserRoleInput;
   AddUserTagInput: Types.AddUserTagInput;
   ApiKey: ResolverTypeWrapper<Types.ApiKey>;
+  ApiKeyAttachableGrants: ResolverTypeWrapper<Types.ApiKeyAttachableGrants>;
+  ApiKeyAttachablePermission: ResolverTypeWrapper<Types.ApiKeyAttachablePermission>;
   ApiKeyPage: ResolverTypeWrapper<Types.ApiKeyPage>;
   ApiKeySearchableField: Types.ApiKeySearchableField;
   ApiKeySortInput: Types.ApiKeySortInput;
@@ -507,6 +509,7 @@ export type ResolversTypes = ResolversObject<{
   Scope: Types.Scope;
   Searchable: ResolverTypeWrapper<ResolversInterfaceTypes<ResolversTypes>['Searchable']>;
   SessionExportData: ResolverTypeWrapper<Types.SessionExportData>;
+  SetApiKeyPermissionsInput: Types.SetApiKeyPermissionsInput;
   SetMyNotificationPreferenceInput: Types.SetMyNotificationPreferenceInput;
   SetMyPrimaryMfaDeviceInput: Types.SetMyPrimaryMfaDeviceInput;
   SetProjectExportableApiKeySecretsInput: Types.SetProjectExportableApiKeySecretsInput;
@@ -649,6 +652,8 @@ export type ResolversParentTypes = ResolversObject<{
   AddUserRoleInput: Types.AddUserRoleInput;
   AddUserTagInput: Types.AddUserTagInput;
   ApiKey: Types.ApiKey;
+  ApiKeyAttachableGrants: Types.ApiKeyAttachableGrants;
+  ApiKeyAttachablePermission: Types.ApiKeyAttachablePermission;
   ApiKeyPage: Types.ApiKeyPage;
   ApiKeySortInput: Types.ApiKeySortInput;
   AssignRolePermissionInput: Types.AssignRolePermissionInput;
@@ -899,6 +904,7 @@ export type ResolversParentTypes = ResolversObject<{
   Scope: Types.Scope;
   Searchable: ResolversInterfaceTypes<ResolversParentTypes>['Searchable'];
   SessionExportData: Types.SessionExportData;
+  SetApiKeyPermissionsInput: Types.SetApiKeyPermissionsInput;
   SetMyNotificationPreferenceInput: Types.SetMyNotificationPreferenceInput;
   SetMyPrimaryMfaDeviceInput: Types.SetMyPrimaryMfaDeviceInput;
   SetProjectExportableApiKeySecretsInput: Types.SetProjectExportableApiKeySecretsInput;
@@ -1136,6 +1142,7 @@ export type ApiKeyResolvers<
   isRevoked?: Resolver<ResolversTypes['Boolean'], ParentType, ContextType>;
   lastUsedAt?: Resolver<Types.Maybe<ResolversTypes['Date']>, ParentType, ContextType>;
   name?: Resolver<Types.Maybe<ResolversTypes['String']>, ParentType, ContextType>;
+  permissions?: Resolver<Types.Maybe<Array<ResolversTypes['Permission']>>, ParentType, ContextType>;
   revokedAt?: Resolver<Types.Maybe<ResolversTypes['Date']>, ParentType, ContextType>;
   revokedBy?: Resolver<Types.Maybe<ResolversTypes['ID']>, ParentType, ContextType>;
   revokedByUser?: Resolver<Types.Maybe<ResolversTypes['User']>, ParentType, ContextType>;
@@ -1144,6 +1151,28 @@ export type ApiKeyResolvers<
   __isTypeOf?: IsTypeOfResolverFn<ParentType, ContextType>;
 }>;
 
+export type ApiKeyAttachableGrantsResolvers<
+  ContextType = any,
+  ParentType extends ResolversParentTypes['ApiKeyAttachableGrants'] =
+    ResolversParentTypes['ApiKeyAttachableGrants'],
+> = ResolversObject<{
+  permissions?: Resolver<
+    Array<ResolversTypes['ApiKeyAttachablePermission']>,
+    ParentType,
+    ContextType
+  >;
+  roles?: Resolver<Array<ResolversTypes['Role']>, ParentType, ContextType>;
+}>;
+
+export type ApiKeyAttachablePermissionResolvers<
+  ContextType = any,
+  ParentType extends ResolversParentTypes['ApiKeyAttachablePermission'] =
+    ResolversParentTypes['ApiKeyAttachablePermission'],
+> = ResolversObject<{
+  machineOnly?: Resolver<ResolversTypes['Boolean'], ParentType, ContextType>;
+  permission?: Resolver<ResolversTypes['Permission'], ParentType, ContextType>;
+}>;
+
 export type ApiKeyPageResolvers<
   ContextType = any,
   ParentType extends ResolversParentTypes['ApiKeyPage'] = ResolversParentTypes['ApiKeyPage'],
@@ -2001,6 +2030,12 @@ export type MutationResolvers<
     ContextType,
     RequireFields<Types.MutationRotateWebhookSubscriptionSecretArgs, 'input'>
   >;
+  setApiKeyPermissions?: Resolver<
+    ResolversTypes['ApiKey'],
+    ParentType,
+    ContextType,
+    RequireFields<Types.MutationSetApiKeyPermissionsArgs, 'input'>
+  >;
   setMyNotificationPreference?: Resolver<
     ResolversTypes['NotificationPreference'],
     ParentType,
@@ -2981,6 +3016,12 @@ export type QueryResolvers<
   ParentType extends ResolversParentTypes['Query'] = ResolversParentTypes['Query'],
 > = ResolversObject<{
   _empty?: Resolver<Types.Maybe<ResolversTypes['String']>, ParentType, ContextType>;
+  apiKeyAttachableGrants?: Resolver<
+    ResolversTypes['ApiKeyAttachableGrants'],
+    ParentType,
+    ContextType,
+    RequireFields<Types.QueryApiKeyAttachableGrantsArgs, 'scope'>
+  >;
   apiKeys?: Resolver<
     ResolversTypes['ApiKeyPage'],
     ParentType,
@@ -3870,6 +3911,8 @@ export type Resolvers<ContextType = any> = ResolversObject<{
   AccountRole?: AccountRoleResolvers<ContextType>;
   AccountTag?: AccountTagResolvers<ContextType>;
   ApiKey?: ApiKeyResolvers<ContextType>;
+  ApiKeyAttachableGrants?: ApiKeyAttachableGrantsResolvers<ContextType>;
+  ApiKeyAttachablePermission?: ApiKeyAttachablePermissionResolvers<ContextType>;
   ApiKeyPage?: ApiKeyPageResolvers<ContextType>;
   Auditable?: AuditableResolvers<ContextType>;
   AuthSignupPolicy?: AuthSignupPolicyResolvers<ContextType>;

package/src/generated/schema-types.ts

@@ -340,14 +340,29 @@ export type ApiKey = Auditable & {
   isRevoked: Scalars['Boolean']['output'];
   lastUsedAt?: Maybe<Scalars['Date']['output']>;
   name?: Maybe<Scalars['String']['output']>;
+  /** Permissions this API key carries instead of a role (project-level keys only). Null for user-scoped keys and for role keys. */
+  permissions?: Maybe<Array<Permission>>;
   revokedAt?: Maybe<Scalars['Date']['output']>;
   revokedBy?: Maybe<Scalars['ID']['output']>;
   revokedByUser?: Maybe<User>;
-  /** Role bound to this API key (project-level keys only). Null for user-scoped keys. */
+  /** Standard role bound to this API key (project-level keys only). Null for user-scoped keys and for keys that carry permissions. */
   role?: Maybe<Role>;
   updatedAt: Scalars['Date']['output'];
 };
 
+export type ApiKeyAttachableGrants = {
+  __typename?: 'ApiKeyAttachableGrants';
+  permissions: Array<ApiKeyAttachablePermission>;
+  roles: Array<Role>;
+};
+
+export type ApiKeyAttachablePermission = {
+  __typename?: 'ApiKeyAttachablePermission';
+  /** True for a permission meant for credentials only (such as ProjectUser:ExportCredentials): it can be given to a key by a holder of its gate permission, without holding it. */
+  machineOnly: Scalars['Boolean']['output'];
+  permission: Permission;
+};
+
 export type ApiKeyPage = PaginatedResults & {
   __typename?: 'ApiKeyPage';
   apiKeys: Array<ApiKey>;
@@ -610,7 +625,9 @@ export type CreateApiKeyInput = {
   description?: InputMaybe<Scalars['String']['input']>;
   expiresAt?: InputMaybe<Scalars['Date']['input']>;
   name?: InputMaybe<Scalars['String']['input']>;
-  /** Required when scope.tenant is accountProject or organizationProject: the parent-tenant role the key impersonates. */
+  /** For a project key: the permissions the key carries instead of a role. Give exactly one of `roleId` or `permissionIds`. Each must be covered by what you can do in this scope, except machine-only permissions, which a holder of their gate permission may attach. Not allowed for other scopes. */
+  permissionIds?: InputMaybe<Array<Scalars['ID']['input']>>;
+  /** For a project key (scope.tenant is accountProject or organizationProject): the standard role the key carries. Give exactly one of `roleId` or `permissionIds`. An account project key with neither carries the creator's account role. The role's permissions must be covered by what you can do in this scope. */
   roleId?: InputMaybe<Scalars['ID']['input']>;
   scope: Scope;
 };
@@ -1356,6 +1373,8 @@ export type Mutation = {
   rotateSigningKey: SigningKey;
   /** Rotate the signing secret. The new secret is returned once. */
   rotateWebhookSubscriptionSecret: WebhookSubscriptionWithSecret;
+  /** Replace the permissions a project API key carries. Applied to a role key it converts the key to permissions; the conversion is one way. The key keeps its id, clientId and secret, and the change applies to its next request. Refuses a revoked key. */
+  setApiKeyPermissions: ApiKey;
   setMyNotificationPreference: NotificationPreference;
   setMyPrimaryAuthenticationMethod: UserAuthenticationMethod;
   setMyPrimaryMfaDevice: MfaDevice;
@@ -1731,6 +1750,10 @@ export type MutationRotateWebhookSubscriptionSecretArgs = {
   input: RotateWebhookSubscriptionSecretInput;
 };
 
+export type MutationSetApiKeyPermissionsArgs = {
+  input: SetApiKeyPermissionsInput;
+};
+
 export type MutationSetMyNotificationPreferenceArgs = {
   input: SetMyNotificationPreferenceInput;
 };
@@ -2706,6 +2729,8 @@ export type ProjectUserPermission = Auditable & {
 export type Query = {
   __typename?: 'Query';
   _empty?: Maybe<Scalars['String']['output']>;
+  /** What the caller may give a new project API key in this scope: the permissions (machine-only ones flagged) and the standard roles whose permissions the caller covers. Project scopes only. */
+  apiKeyAttachableGrants: ApiKeyAttachableGrants;
   apiKeys: ApiKeyPage;
   /** Public signup policy. No authentication required. */
   authSignupPolicy: AuthSignupPolicy;
@@ -2779,6 +2804,10 @@ export type Query = {
   webhookSubscriptions: Array<WebhookSubscription>;
 };
 
+export type QueryApiKeyAttachableGrantsArgs = {
+  scope: Scope;
+};
+
 export type QueryApiKeysArgs = {
   ids?: InputMaybe<Array<Scalars['ID']['input']>>;
   limit?: InputMaybe<Scalars['Int']['input']>;
@@ -3704,6 +3733,13 @@ export type SessionExportData = {
   userAgent?: Maybe<Scalars['String']['output']>;
 };
 
+export type SetApiKeyPermissionsInput = {
+  id: Scalars['ID']['input'];
+  /** The complete set of permissions the key carries afterwards; it may not be empty. Permissions you add must be covered by what you can do in this scope (machine-only permissions: see `apiKeyAttachableGrants`); permissions you leave out are removed. */
+  permissionIds: Array<Scalars['ID']['input']>;
+  scope: Scope;
+};
+
 export type SetMyNotificationPreferenceInput = {
   /** Notification preference category (security, iam, membership, integrations). */
   category: Scalars['String']['input'];

package/src/operations/api-keys/get-api-key-attachable-grants.graphql

@@ -0,0 +1,23 @@
+query GetApiKeyAttachableGrants($scope: Scope!) {
+  apiKeyAttachableGrants(scope: $scope) {
+    permissions {
+      machineOnly
+      permission {
+        id
+        name
+        action
+        description
+        resource {
+          id
+          slug
+          name
+        }
+      }
+    }
+    roles {
+      id
+      name
+      description
+    }
+  }
+}

package/src/operations/api-keys/get-api-key-role-permissions.graphql

@@ -0,0 +1,28 @@
+query GetApiKeyRolePermissions($scope: Scope!, $ids: [ID!]) {
+  roles(scope: $scope, ids: $ids, limit: 1, page: 1) {
+    roles {
+      id
+      name
+      # The permissions a role key resolves to come from the role's groups. `groups(scope)` does not
+      # list the standard groups, so they are read through the role.
+      groups {
+        id
+        permissions {
+          id
+          name
+          action
+          description
+          resource {
+            id
+            slug
+            name
+          }
+        }
+      }
+      rolePermissions {
+        id
+        permissionId
+      }
+    }
+  }
+}

package/src/operations/api-keys/get-api-keys.graphql

@@ -25,6 +25,17 @@ query GetApiKeys(
         id
         name
       }
+      permissions {
+        id
+        name
+        action
+        description
+        resource {
+          id
+          slug
+          name
+        }
+      }
       createdByUser {
         id
         name

package/src/operations/api-keys/set-api-key-permissions.graphql

@@ -0,0 +1,27 @@
+mutation SetApiKeyPermissions($input: SetApiKeyPermissionsInput!) {
+  setApiKeyPermissions(input: $input) {
+    id
+    clientId
+    name
+    description
+    expiresAt
+    lastUsedAt
+    isRevoked
+    updatedAt
+    role {
+      id
+      name
+    }
+    permissions {
+      id
+      name
+      action
+      description
+      resource {
+        id
+        slug
+        name
+      }
+    }
+  }
+}

package/src/schema/api-keys/inputs/create-api-key.graphql

@@ -4,7 +4,11 @@ input CreateApiKeyInput {
   expiresAt: Date
   scope: Scope!
   """
-  Required when scope.tenant is accountProject or organizationProject: the parent-tenant role the key impersonates.
+  For a project key (scope.tenant is accountProject or organizationProject): the standard role the key carries. Give exactly one of `roleId` or `permissionIds`. An account project key with neither carries the creator's account role. The role's permissions must be covered by what you can do in this scope.
   """
   roleId: ID
+  """
+  For a project key: the permissions the key carries instead of a role. Give exactly one of `roleId` or `permissionIds`. Each must be covered by what you can do in this scope, except machine-only permissions, which a holder of their gate permission may attach. Not allowed for other scopes.
+  """
+  permissionIds: [ID!]
 }

package/src/schema/api-keys/inputs/set-api-key-permissions.graphql

@@ -0,0 +1,8 @@
+input SetApiKeyPermissionsInput {
+  scope: Scope!
+  id: ID!
+  """
+  The complete set of permissions the key carries afterwards; it may not be empty. Permissions you add must be covered by what you can do in this scope (machine-only permissions: see `apiKeyAttachableGrants`); permissions you leave out are removed.
+  """
+  permissionIds: [ID!]!
+}

package/src/schema/api-keys/mutations/set-api-key-permissions.graphql

@@ -0,0 +1,6 @@
+extend type Mutation {
+  """
+  Replace the permissions a project API key carries. Applied to a role key it converts the key to permissions; the conversion is one way. The key keeps its id, clientId and secret, and the change applies to its next request. Refuses a revoked key.
+  """
+  setApiKeyPermissions(input: SetApiKeyPermissionsInput!): ApiKey!
+}

package/src/schema/api-keys/queries/get-api-key-attachable-grants.graphql

@@ -0,0 +1,6 @@
+extend type Query {
+  """
+  What the caller may give a new project API key in this scope: the permissions (machine-only ones flagged) and the standard roles whose permissions the caller covers. Project scopes only.
+  """
+  apiKeyAttachableGrants(scope: Scope!): ApiKeyAttachableGrants!
+}

package/src/schema/api-keys/types/api-key-attachable-grants.graphql

@@ -0,0 +1,4 @@
+type ApiKeyAttachableGrants {
+  permissions: [ApiKeyAttachablePermission!]!
+  roles: [Role!]!
+}

package/src/schema/api-keys/types/api-key-attachable-permission.graphql

@@ -0,0 +1,7 @@
+type ApiKeyAttachablePermission {
+  permission: Permission!
+  """
+  True for a permission meant for credentials only (such as ProjectUser:ExportCredentials): it can be given to a key by a holder of its gate permission, without holding it.
+  """
+  machineOnly: Boolean!
+}

package/src/schema/api-keys/types/api-key.graphql

@@ -15,7 +15,11 @@ type ApiKey implements Auditable {
   createdByUser: User
   revokedByUser: User
   """
-  Role bound to this API key (project-level keys only). Null for user-scoped keys.
+  Standard role bound to this API key (project-level keys only). Null for user-scoped keys and for keys that carry permissions.
   """
   role: Role
+  """
+  Permissions this API key carries instead of a role (project-level keys only). Null for user-scoped keys and for role keys.
+  """
+  permissions: [Permission!]
 }

package/src/sdl-contract.test.ts

@@ -54,10 +54,12 @@ describe('operation documents', () => {
   // 138 after operator-set-email: SetProjectUserEmailDocument.
   // 140 after operator-set-password: SetProjectUserPasswordDocument, ExportProjectUserCredentialsDocument.
   // 141 after exportable-api-key-secret opt-in: SetProjectExportableApiKeySecretsDocument.
+  // 144 after api-key scopes web: GetApiKeyAttachableGrantsDocument, SetApiKeyPermissionsDocument,
+  // GetApiKeyRolePermissionsDocument.
   // Updating this number is the point of the pin, not a nuisance: every change
   // to it should be a line in a commit message.
   it('finds every document under src/operations', () => {
-    expect(files).toHaveLength(141);
+    expect(files).toHaveLength(144);
   });
 
   it.each(files.map((f) => [relative(process.cwd(), f), f]))('%s validates', (_label, file) => {