feat: allow either permission id or slug in permission related requests.

go/apps/api/openapi/spec/paths/v2/keys/deleteKey/KeysDeleteKeyResponseData.yaml → go/apps/api/openapi/spec/common/EmptyResponse.yaml

@@ -1,4 +1,4 @@
 type: object
 properties: {}
 additionalProperties: false
-description: Empty response object by design. A successful response indicates the key was deleted successfully.
+description: Empty response object by design. A successful response indicates this operation was successfully executed.

go/apps/api/openapi/spec/common/KeyResponseData.yaml

@@ -60,7 +60,7 @@ properties:
     type: array
     items:
       type: string
-      description: List of permissions granted to this key.
+      description: List of permission slugs granted to this key.
     example:
       - documents.read
       - documents.write

go/apps/api/openapi/spec/common/permission.yaml

@@ -21,11 +21,11 @@ properties:
       Names must be unique within your workspace to avoid confusion and conflicts.
     example: "users.read"
   slug:
+    pattern: ^[a-zA-Z0-9_:\-\.\*]+$
     type: string
     minLength: 1
     maxLength: 512
-    description: |
-      The URL-safe identifier when this permission was created.
+    description: The URL-safe identifier when this permission was created.
     example: users-read
   description:
     type: string
@@ -36,18 +36,7 @@ properties:
       Include information about what resources can be accessed and what actions can be performed.
       Not visible to end users - this is for internal documentation and team clarity.
     example: "Allows reading user profile information and account details"
-  createdAt:
-    type: integer
-    format: int64
-    minimum: 0
-    maximum: 9223372036854775807 # Max int64 value for future-proofing
-    description: |
-      Unix timestamp in milliseconds indicating when this permission was first created.
-      Useful for auditing and understanding the evolution of your permission structure.
-      Automatically set by the system and cannot be modified.
-    example: 1701425400000
 required:
   - id
   - name
   - slug
-  - createdAt

go/apps/api/openapi/spec/common/role.yaml

@@ -2,18 +2,13 @@ type: object
 properties:
   id:
     type: string
-    minLength: 3
-    maxLength: 255
-    pattern: "^[a-zA-Z0-9_]+$"
     description: |
       The unique identifier for this role within Unkey's system.
       Generated automatically when the role is created and used to reference this role in API operations.
       Always begins with 'role_' followed by alphanumeric characters and underscores.
     example: role_1234567890abcdef
   name:
     type: string
-    minLength: 1
-    maxLength: 512
     description: |
       The human-readable name for this role that describes its function.
       Should be descriptive enough for administrators to understand what access this role provides.
@@ -22,23 +17,12 @@ properties:
     example: "support.readonly"
   description:
     type: string
-    maxLength: 2048
     description: |
       Optional detailed explanation of what this role encompasses and what access it provides.
       Helps team members understand the role's scope, intended use cases, and security implications.
       Include information about what types of users should receive this role and what they can accomplish.
       Not visible to end users - this is for internal documentation and access control audits.
     example: "Provides read-only access for customer support representatives to view user accounts and support tickets"
-  createdAt:
-    type: integer
-    format: int64
-    minimum: 0
-    maximum: 9223372036854775807 # Max int64 value for future-proofing
-    description: |
-      Unix timestamp in milliseconds indicating when this role was first created.
-      Useful for auditing and understanding the evolution of your access control structure.
-      Automatically set by the system and cannot be modified.
-    example: 1701425400000
   permissions:
     type: array
     items:
@@ -54,5 +38,4 @@ required:
   - id
   - name
   - permissions
-  - createdAt
 additionalProperties: false

go/apps/api/openapi/spec/paths/v2/apis/deleteApi/V2ApisDeleteApiResponseBody.yaml

@@ -1,9 +1,12 @@
 type: object
 required:
   - meta
+  - data
 properties:
   meta:
     $ref: "../../../../common/Meta.yaml"
+  data:
+    $ref: "../../../../common/EmptyResponse.yaml"
 additionalProperties: false
 examples:
   successfulDeletion:

go/apps/api/openapi/spec/paths/v2/keys/addPermissions/V2KeysAddPermissionsRequestBody.yaml

@@ -11,56 +11,21 @@ properties:
     description: |
       Specifies which key receives the additional permissions using the database identifier returned from `keys.createKey`.
       Do not confuse this with the actual API key string that users include in requests.
-      Added permissions supplement existing permissions and roles without replacing them.
-      Permission changes take effect immediately but may take up to 30 seconds to propagate across all regions.
     example: key_2cGKbMxRyIzhCxo1Idjz8q
   permissions:
     type: array
     minItems: 1
-    maxItems: 1000 # Allow extensive permission sets for complex applications
+    maxItems: 1000
     description: |
       Grants additional permissions to the key through direct assignment or automatic creation.
       Duplicate permissions are ignored automatically, making this operation idempotent.
-      Use either ID for existing permissions or slug for new permissions with optional auto-creation.
 
-      Permission changes take effect immediately but cache propagation across regions may take up to 30 seconds.
       Adding permissions never removes existing permissions or role-based permissions.
-    items:
-      type: object
-      properties:
-        id:
-          type: string
-          minLength: 3
-          maxLength: 255 # Reasonable upper bound for database identifiers
-          pattern: "^[a-zA-Z0-9_]+$"
-          description: |
-            References an existing permission by its database identifier.
-            Use when you know the exact permission ID and want to ensure you're referencing a specific permission.
-            Takes precedence over slug when both are provided in the same object.
-            The referenced permission must already exist in your workspace.
-          example: perm_1n9McEIBSqy44Qy7hzWyM5
-        slug:
-          type: string
-          minLength: 1
-          maxLength: 100 # Keep permission names concise and readable
-          pattern: "^[a-zA-Z0-9_.]+$"
-          description: |
-            Identifies the permission by its human-readable name using hierarchical naming patterns.
-            Use `resource.action` format for logical organization and verification flexibility.
-            Slugs must be unique within your `workspace` and support wildcard matching during verification.
-            Combined with `create=true`, allows automatic permission creation for streamlined workflows.
-          example: documents.write
-        create:
-          type: boolean
-          default: false
-          description: |
-            Enables automatic permission creation when the specified slug does not exist.
-            Only works with slug-based references, not ID-based references.
-            Requires the `rbac.*.create_permission` permission on your root key.
 
-            Created permissions are permanent and visible workspace-wide to all API keys.
-            Use carefully to avoid permission proliferation from typos or uncontrolled creation.
-            Consider centralizing permission creation in controlled processes for better governance.
-            Auto-created permissions use the slug as both the name and identifier.
-      additionalProperties: false
+      Any permissions that do not exist will be auto created if the root key has permissions, otherwise this operation will fail with a 403 error.
+    items:
+      type: string
+      minLength: 3
+      pattern: ^[a-zA-Z0-9_:\-\.\*]+$
+      description: Specify the permission by its slug.
 additionalProperties: false

go/apps/api/openapi/spec/paths/v2/keys/addPermissions/V2KeysAddPermissionsResponseData.yaml

@@ -12,27 +12,4 @@ description: |-
   - For a complete permission picture, use `/v2/keys.getKey` instead
   - An empty array indicates the key has no direct permissions assigned
 items:
-  type: object
-  required:
-    - id
-    - name
-    - slug
-  properties:
-    id:
-      type: string
-      description:
-        The unique identifier of the permission (begins with `perm_`).
-        This ID can be used in other API calls to reference this specific permission.
-        IDs are guaranteed unique and won't change, making them ideal for scripting
-        and automation. You can store these IDs in your system for consistent
-        reference.
-      example: perm_1n9McEIBSqy44Qy7hzWyM5
-    name:
-      type: string
-      description: "The human-readable name of the permission. "
-      example: Can write documents
-    slug:
-      type: string
-      description: |-
-        The slug of the permission, typically following a `resource.action` pattern like `documents.read`.
-      example: documents.write
+  "$ref": "../../../../common/Permission.yaml"

go/apps/api/openapi/spec/paths/v2/keys/addRoles/V2KeysAddRolesRequestBody.yaml

@@ -21,36 +21,13 @@ properties:
     description: |
       Assigns additional roles to the key through direct assignment to existing workspace roles.
       Operations are idempotent - adding existing roles has no effect and causes no errors.
-      Use either ID for existing roles or name for human-readable references.
 
       All roles must already exist in the workspace - roles cannot be created automatically.
       Invalid roles cause the entire operation to fail atomically, ensuring consistent state.
-      Role assignments take effect immediately but cache propagation across regions may take up to 30 seconds.
     items:
-      type: object
-      properties:
-        id:
-          type: string
-          minLength: 3
-          maxLength: 255 # Reasonable upper bound for database identifiers
-          pattern: "^[a-zA-Z0-9_]+$"
-          description: |
-            References an existing role by its database identifier.
-            Use when you know the exact role ID and want to ensure you're referencing a specific role.
-            Takes precedence over name when both are provided in the same object.
-            Essential for automation scripts where role names might change but IDs remain stable.
-          example: role_1n9McEIBSqy44Qy7hzWyM5
-        name:
-          type: string
-          minLength: 1
-          maxLength: 100 # Keep role names concise and readable
-          pattern: "^[a-zA-Z][a-zA-Z0-9_-]*$"
-          description: |
-            Identifies the role by its human-readable name within the workspace.
-            Role names must start with a letter and contain only letters, numbers, underscores, or hyphens.
-            Names must be unique within the workspace and are case-sensitive.
-            More readable than IDs but vulnerable to integration breaks if roles are renamed.
-            Use IDs for automation and names for human-configured integrations.
-          example: admin
-      additionalProperties: false
+      type: string
+      minLength: 3
+      maxLength: 255 # Reasonable upper bound for database identifiers
+      pattern: "^[a-zA-Z][a-zA-Z0-9._-]*$"
+      description: Specify the role by name.
 additionalProperties: false

go/apps/api/openapi/spec/paths/v2/keys/addRoles/V2KeysAddRolesResponseData.yaml

@@ -13,24 +13,4 @@ description: |-
   - This only shows direct role assignments, not inherited or nested roles
   - Role permissions are not expanded in this response - use keys.getKey for full details
 items:
-  type: object
-  required:
-    - id
-    - name
-  properties:
-    id:
-      type: string
-      description: The unique identifier of the role (begins with `role_`).
-        This ID can be used in other API calls to reference this specific role.
-        Role IDs are immutable and guaranteed to be unique within your Unkey
-        workspace, making them reliable reference points for integration and
-        automation systems.
-      example: role_1n9McEIBSqy44Qy7hzWyM5
-    name:
-      type: string
-      description: The name of the role. This is a human-readable identifier
-        that's unique within your workspace. Role names help identify what access
-        level or function a role provides. Common patterns include naming by
-        access level (`admin`, `editor`, `viewer`), by department (`billing_manager`,
-        `support_agent`), or by feature area (`analytics_user`, `dashboard_admin`).
-      example: admin
+  "$ref": "../../../../common/role.yaml"

go/apps/api/openapi/spec/paths/v2/keys/deleteKey/V2KeysDeleteKeyResponseBody.yaml

@@ -1,11 +1,12 @@
 type: object
 required:
   - meta
+  - data
 properties:
   meta:
     "$ref": "../../../../common/Meta.yaml"
   data:
-    "$ref": "./KeysDeleteKeyResponseData.yaml"
+    "$ref": "../../../../common/EmptyResponse.yaml"
 additionalProperties: false
 examples:
   userDeletionSuccess:

go/apps/api/openapi/spec/paths/v2/keys/removePermissions/V2KeysRemovePermissionsRequestBody.yaml

@@ -11,42 +11,20 @@ properties:
     description: |
       Specifies which key to remove permissions from using the database identifier returned from `keys.createKey`.
       Do not confuse this with the actual API key string that users include in requests.
-      Removing permissions only affects direct assignments, not permissions inherited from roles.
-      Permission changes take effect immediately but may take up to 30 seconds to propagate across all regions.
     example: key_2cGKbMxRyIzhCxo1Idjz8q
   permissions:
     type: array
     minItems: 1
     maxItems: 1000 # Allow extensive permission sets for complex applications
     description: |
       Removes direct permissions from the key without affecting role-based permissions.
-      Operations are idempotent - removing non-existent permissions has no effect and causes no errors.
-      Use either ID for existing permissions or name for exact string matching.
+
+      You can either use a permission slug, or the permission ID.
 
       After removal, verification checks for these permissions will fail unless granted through roles.
-      Permission changes take effect immediately but cache propagation across regions may take up to 30 seconds.
-      Removing all direct permissions does not disable the key, only removes its direct permission grants.
     items:
-      type: object
-      properties:
-        id:
-          type: string
-          minLength: 3
-          maxLength: 255 # Reasonable upper bound for database identifiers
-          pattern: "^[a-zA-Z0-9_]+$"
-          description: |
-            References the permission to remove by its database identifier.
-            Use when you know the exact permission ID and want to ensure you're removing a specific permission.
-            Takes precedence over name when both are provided in the same object.
-            Essential for automation scripts where precision prevents accidental permission removal.
-          example: perm_1n9McEIBSqy44Qy7hzWyM5
-        slug:
-          type: string
-          minLength: 1
-          maxLength: 100 # Keep permission slugs concise and readable
-          pattern: "^[a-zA-Z0-9_.]+$"
-          description: |
-            Identifies the permission by slug for removal from the key's direct assignment list.
-          example: documents.write
-      additionalProperties: false
+      type: string
+      minLength: 3
+      pattern: ^[a-zA-Z0-9_:\-\.\*]+$
+      description: Specify the permission by its slug.
 additionalProperties: false

go/apps/api/openapi/spec/paths/v2/keys/removePermissions/V2KeysRemovePermissionsResponseData.yaml

@@ -2,47 +2,11 @@ type: array
 description: |-
   Complete list of all permissions directly assigned to the key after the removal operation (remaining permissions only).
 
-  This response includes:
-  - All direct permissions still assigned to the key after removal
-  - Permissions sorted alphabetically by name for consistent response format
-  - Both the permission ID and name for each remaining permission
-
-  Important notes:
+  Notes:
   - This list does NOT include permissions granted through roles
   - For a complete permission picture, use `/v2/keys.getKey` instead
   - An empty array indicates the key has no direct permissions assigned
   - Any cached versions of the key are immediately invalidated to ensure consistency
   - Changes to permissions take effect within seconds for new verifications
 items:
-  type: object
-  required:
-    - id
-    - name
-    - slug
-  properties:
-    id:
-      type: string
-      description:
-        The unique identifier of the permission (begins with `perm_`).
-        This ID can be used in other API calls to reference this specific permission.
-        IDs are guaranteed unique and won't change, making them ideal for scripting
-        and automation. You can store these IDs in your system for consistent
-        reference.
-      example: perm_1n9McEIBSqy44Qy7hzWyM5
-    name:
-      type: string
-      description: The name of the permission
-      example: documents.write
-    slug:
-      type: string
-      description: |-
-        The slug of the permission, typically following a `resource.action` pattern like `documents.read`. Names are human-readable identifiers used both for assignment and verification.
-
-        During verification:
-        - The exact name is matched (e.g., `documents.read`)
-        - Hierarchical wildcards are supported in verification requests
-        - A key with permission `documents.*` grants access to `documents.read`, `documents.write`, etc.
-        - Wildcards can appear at any level: `billing.*.view` matches `billing.invoices.view` and `billing.payments.view`
-
-        However, when adding permissions, you must specify each exact permission - wildcards are not valid for assignment.
-      example: documents.write
+  "$ref": "../../../../common/Permission.yaml"