chore: remove identityID from v2

go/apps/api/openapi/openapi.yaml

@@ -201,8 +201,8 @@ components:
             Cannot configure refill settings when credits is null, and refillDay requires monthly interval.
             Essential for implementing usage-based pricing and subscription quotas.
         ratelimits:
-          type: array
           nullable: true
+          type: array
           maxItems: 50 # Reasonable limit for rate limit configurations per key
           items:
             "$ref": "#/components/schemas/RatelimitRequest"
@@ -223,12 +223,8 @@ components:
     KeysUpdateKeyResponseData:
       type: object
       properties: {}
-      description:
-        Empty response object by design. A successful response indicates
-        the key was updated successfully. The endpoint doesn't return the updated
-        key to reduce response size and avoid exposing sensitive information. Changes
-        may take up to 30 seconds to propagate to all regions due to cache invalidation
-        delays. If you need the updated key state, use a subsequent call to `keys.getKey`.
+      additionalProperties: false
+      description: Empty response object by design. A successful response indicates the key was updated successfully.
     V2KeysUpdateKeyResponseBody:
       type: object
       required:
@@ -270,11 +266,8 @@ components:
     KeysDeleteKeyResponseData:
       type: object
       properties: {}
-      description: |
-        Confirms successful key deletion with no additional data returned.
-        Deletion immediately invalidates the key in the primary database but cache propagation across regions may take up to 30 seconds.
-        During this propagation window, some verification attempts might still succeed in certain regions due to eventual consistency.
-        Monitor your application logs during the propagation period to ensure no unexpected authentication successes occur.
+      additionalProperties: false
+      description: Empty response object by design. A successful response indicates the key was deleted successfully.
     V2KeysDeleteKeyResponseBody:
       type: object
       required:
@@ -318,7 +311,6 @@ components:
             Never log, cache, or store API keys in your system as they provide full access to user resources.
             Include the full key exactly as provided - even minor modifications will cause a not found error.
           example: prefix_f4cc2d765275c206b7d76ff0e92e583067c4e33603fb4055d7ba3031cd7ce36a
-
       additionalProperties: false
       oneOf:
         - required:
@@ -1198,7 +1190,6 @@ components:
             - name: heavy_operations
               limit: 10
               duration: 3600000
-              async: false
         enabled:
           type: boolean
           default: true
@@ -1558,9 +1549,6 @@ components:
     Identity:
       type: object
       properties:
-        id:
-          type: string
-          description: Identity ID
         externalId:
           type: string
           description: External identity ID
@@ -1573,7 +1561,6 @@ components:
             "$ref": "#/components/schemas/RatelimitResponse"
           description: Identity ratelimits
       required:
-        - id
         - externalId
         - ratelimits
     KeyCreditsData:
@@ -2308,20 +2295,6 @@ components:
           default: false
     IdentitiesCreateIdentityResponseData:
       type: object
-      properties:
-        identityId:
-          description: |-
-            The unique identifier for this identity in Unkey's system (begins with `id_`).
-
-            This ID is generated automatically and used internally by Unkey to reference this identity. While you typically don't need to store this value (your `externalId` is sufficient), it can be useful to record it for:
-            - Debugging purposes
-            - Advanced API operations
-            - Integration with Unkey's analytics
-
-            Unlike `externalId` which comes from your system, this ID is guaranteed unique across all Unkey `workspaces`.
-          type: string
-      required:
-        - identityId
     V2IdentitiesCreateIdentityResponseBody:
       type: object
       required:
@@ -2335,41 +2308,21 @@ components:
     V2IdentitiesGetIdentityRequestBody:
       type: object
       properties:
-        identityId:
-          type: string
-          minLength: 3
-          description:
-            The Unkey identity ID to retrieve (begins with 'id_'). Use
-            either identityId or externalId to specify which identity to fetch. If
-            both are provided, identityId takes precedence.
-          example: id_1234567890abcdef
         externalId:
           type: string
           minLength: 1
           description:
             The external ID of the identity to retrieve. This is the ID
-            from your own system that was used during identity creation. Use either
-            identityId or externalId to specify which identity to fetch. If both are
-            provided, identityId takes precedence.
+            from your own system that was used during identity creation.
           example: user_abc123
       additionalProperties: false
-      oneOf:
-        - required:
-            - identityId
-        - required:
-            - externalId
+      required:
+        - externalId
     IdentitiesGetIdentityResponseData:
       type: object
       required:
-        - id
         - externalId
       properties:
-        id:
-          type: string
-          description:
-            The unique identifier for this identity in Unkey's system (begins
-            with 'id_').
-          example: id_1234567890abcdef
         externalId:
           type: string
           description:
@@ -2451,28 +2404,11 @@ components:
           minLength: 3
           description: |
             The id of this identity in your system.
-
-            This should match the externalId value you used when creating the identity. You can use this field when you know the specific externalId but don't have the Unkey identityId. Only one of externalId or identityId is required.
-
+            This should match the externalId value you used when creating the identity.
             This identifier typically comes from your authentication system and could be a userId, organizationId, or any other stable unique identifier in your application.
           example: user_123
-        identityId:
-          type: string
-          minLength: 3
-          description: |-
-            The Unkey Identity ID (begins with 'id_').
-
-            This is the internal unique identifier generated by Unkey when the identity was created. Use this when you have the specific Unkey ID and want to ensure you're targeting the exact identity. This is especially useful in automation scripts or when you need to guarantee you're operating on a specific identity regardless of externalId changes.
-
-            Only one of externalId or identityId is required.
-          example: id_123
-      oneOf:
-        - required:
-            - externalId
-          description: Identify by external ID from your system
-        - required:
-            - identityId
-          description: Identify by Unkey's internal identity ID
+      required:
+        - externalId
     V2IdentitiesDeleteIdentityResponseBody:
       type: object
       description:
@@ -3644,27 +3580,14 @@ components:
     V2IdentitiesUpdateIdentityRequestBody:
       type: object
       properties:
-        identityId:
-          type: string
-          minLength: 3
-          maxLength: 255 # Reasonable upper bound for database identifiers
-          pattern: "^[a-zA-Z0-9_]+$"
-          description: |
-            Specifies which identity to update using the Unkey database identifier.
-            Takes precedence over externalId when both are provided in the same request.
-            Use this when you have stored the Unkey identity ID from previous API calls.
-            Essential for direct identity management when you track Unkey's internal identifiers.
-          example: id_01H9TQPP77V5E48E9SH0BG0ZQX
         externalId:
           type: string
           minLength: 3
           maxLength: 255 # Match database varchar limits for external identifiers
           pattern: "^[a-zA-Z0-9_.-]+$"
           description: |
             Specifies which identity to update using your system's identifier from identity creation.
-            Ignored when identityId is also provided in the same request.
             Use this when you track identities by your own user IDs, organization IDs, or tenant identifiers.
-            More convenient than identityId when integrating with existing user management systems.
             Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
           example: user_abc123
         meta:
@@ -3695,23 +3618,13 @@ components:
               limit: 1000
               duration: 3600000
       additionalProperties: false
-      anyOf:
-        - required:
-            - identityId
-        - required:
-            - externalId
+      required:
+        - externalId
     IdentitiesUpdateIdentityResponseData:
       type: object
       required:
-        - id
         - externalId
       properties:
-        id:
-          type: string
-          description:
-            The unique identifier for this identity in Unkey's system (begins
-            with 'id_').
-          example: id_01H9TQPP77V5E48E9SH0BG0ZQX
         externalId:
           type: string
           description: The external identifier for this identity in your system.
@@ -4804,7 +4717,7 @@ paths:
         "404":
           description:
             Not found - The specified identity doesn't exist. This error
-            occurs when no identity matches the provided externalId or identityId.
+            occurs when no identity matches the provided externalId.
             This might happen if the identity was already deleted, never existed,
             or if there's a typo in the identifier. Verify the identity exists before
             attempting deletion.
@@ -4910,8 +4823,7 @@ paths:
           description:
             Bad request - Invalid or missing parameters. This error occurs
             when the request body is malformed, missing required fields, or contains
-            invalid values. Verify that you've provided either a valid externalId
-            or identityId, and that the format of each field meets the requirements.
+            invalid values. Verify that you've provided a valid externalId, and that the format of each field meets the requirements.
           content:
             application/json:
               schema:
@@ -6088,8 +6000,6 @@ paths:
                   value:
                     meta:
                       requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
-                    data:
-                      identityId: id_01H9TQP8NP8JN3X8HWSKPW43JE
           description: OK
         "400":
           description: Bad request
@@ -6133,20 +6043,18 @@ paths:
         - identities
       summary: Retrieve identity information
       description: |-
-        Retrieves detailed information about a specific identity by its Unkey ID or external ID.
+        Retrieves detailed information about a specific identity by its external ID.
 
         Identities in Unkey represent entities in your system (users, organizations, etc.) that can be associated with multiple API keys. This endpoint provides access to:
         - Identity metadata that was stored during creation
         - Rate limiting configurations that apply across all keys for this identity
-        - Mapping between your system's external IDs and Unkey's internal IDs
 
         This endpoint is useful for:
         - Checking if an identity exists
         - Retrieving metadata associated with an identity
         - Viewing rate limit configurations
-        - Finding the Unkey ID for an identity when you only have the external ID
 
-        You must provide either the identityId or externalId parameter to identify which identity to retrieve.
+        You must provide the externalId parameter to identify which identity to retrieve.
       operationId: identities.getIdentity
       x-speakeasy-name-override: getIdentity
       security:
@@ -6157,10 +6065,6 @@ paths:
             schema:
               "$ref": "#/components/schemas/V2IdentitiesGetIdentityRequestBody"
             examples:
-              byIdentityId:
-                summary: Retrieve by Unkey identity ID
-                value:
-                  identityId: id_1234567890abcdef
               byExternalId:
                 summary: Retrieve by external ID
                 value:
@@ -6195,8 +6099,7 @@ paths:
                           limit: 100
                           duration: 3600000
         "400":
-          description:
-            Bad request - Missing both identityId and externalId, or other
+          description: Bad request - Missing the externalId, or other
             validation issues
           content:
             application/json:
@@ -6369,11 +6272,6 @@ paths:
                 description: Deleting using your system's identifier
                 value:
                   externalId: user_abc123
-              byIdentityId:
-                summary: Delete by Unkey identity ID
-                description: Deleting using Unkey's internal identifier
-                value:
-                  identityId: id_01H9TQP8NP8JN3X8HWSKPW43JE
         required: true
       responses:
         "200":
@@ -7440,7 +7338,7 @@ paths:
               updateMetadata:
                 summary: Update identity metadata only
                 value:
-                  identityId: id_01H9TQPP77V5E48E9SH0BG0ZQX
+                  externalId: user_123
                   meta:
                     name: Alice Smith
                     email: alice.updated@example.com

go/apps/api/routes/v2_apis_create_api/handler.go

@@ -44,12 +44,9 @@ func (h *Handler) Handle(ctx context.Context, s *zen.Session) error {
 		return err
 	}
 
-	var req Request
-	err = s.BindBody(&req)
+	req, err := zen.BindBody[Request](s)
 	if err != nil {
-		return fault.Wrap(err,
-			fault.Internal("invalid request body"), fault.Public("The request body is invalid."),
-		)
+		return err
 	}
 
 	err = auth.Verify(ctx, keys.WithPermissions(rbac.Or(

go/apps/api/routes/v2_apis_delete_api/handler.go

@@ -50,14 +50,10 @@ func (h *Handler) Handle(ctx context.Context, s *zen.Session) error {
 		return err
 	}
 
-	var req Request
-	err = s.BindBody(&req)
+	req, err := zen.BindBody[Request](s)
 	if err != nil {
-		return fault.Wrap(err,
-			fault.Internal("invalid request body"), fault.Public("The request body is invalid."),
-		)
+		return err
 	}
-
 	err = auth.Verify(ctx, keys.WithPermissions(rbac.Or(
 		rbac.T(rbac.Tuple{
 			ResourceType: rbac.Api,

go/apps/api/routes/v2_apis_get_api/handler.go

@@ -43,12 +43,9 @@ func (h *Handler) Handle(ctx context.Context, s *zen.Session) error {
 		return err
 	}
 
-	var req Request
-	err = s.BindBody(&req)
+	req, err := zen.BindBody[Request](s)
 	if err != nil {
-		return fault.Wrap(err,
-			fault.Internal("invalid request body"), fault.Public("The request body is invalid."),
-		)
+		return err
 	}
 
 	err = auth.Verify(ctx, keys.WithPermissions(rbac.Or(

go/apps/api/routes/v2_apis_list_keys/200_test.go

@@ -319,7 +319,6 @@ func TestSuccess(t *testing.T) {
 		for _, key := range res.Body.Data {
 			require.NotNil(t, key.Identity)
 			require.Equal(t, identity1ExternalID, key.Identity.ExternalId)
-			require.Equal(t, identity1ID, key.Identity.Id)
 		}
 	})
 
@@ -394,7 +393,6 @@ func TestSuccess(t *testing.T) {
 
 		key := res.Body.Data[0]
 		require.NotNil(t, key.Identity)
-		require.Equal(t, identity1ID, key.Identity.Id)
 		require.Equal(t, identity1ExternalID, key.Identity.ExternalId)
 		require.NotNil(t, key.Identity.Meta)