feat: /v2/keys.whoami endpoint separate from getKey

go/apps/api/openapi/openapi-generated.yaml

@@ -1,5 +1,5 @@
 # Code generated by generate_bundle.go; DO NOT EDIT.
-# Generated at: 2025-07-28T12:12:38Z
+# Generated at: 2025-07-28T13:27:42Z
 # Source: openapi-split.yaml
 
 components:
@@ -891,21 +891,9 @@ components:
                         Use only for legitimate recovery scenarios like user password resets or emergency access.
                         Most applications should keep this false to maintain security best practices and avoid accidental key exposure.
                         Decryption requests are audited and may trigger security alerts in enterprise environments.
-                key:
-                    type: string
-                    minLength: 1
-                    maxLength: 512
-                    description: |
-                        The complete API key string provided by you, including any prefix.
-                        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: sk_1234abcdef5678
             additionalProperties: false
-            oneOf:
-                - required:
-                    - keyId
-                - required:
-                    - key
+            required:
+                - keyId
         V2KeysGetKeyResponseBody:
             type: object
             required:
@@ -1430,6 +1418,31 @@ components:
                 data:
                     "$ref": "#/components/schemas/V2KeysVerifyKeyResponseData"
             additionalProperties: false
+        V2KeysWhoamiRequestBody:
+            type: object
+            properties:
+                key:
+                    type: string
+                    minLength: 1
+                    maxLength: 512
+                    description: |
+                        The complete API key string provided by you, including any prefix.
+                        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: sk_1234abcdef5678
+            additionalProperties: false
+            required:
+                - key
+        V2KeysWhoamiResponseBody:
+            type: object
+            required:
+                - meta
+                - data
+            properties:
+                meta:
+                    "$ref": "#/components/schemas/Meta"
+                data:
+                    "$ref": "#/components/schemas/KeyResponseData"
         V2LivenessResponseBody:
             type: object
             required:
@@ -4987,6 +5000,69 @@ paths:
             tags:
                 - keys
             x-speakeasy-name-override: verifyKey
+    /v2/keys.whoami:
+        post:
+            description: |
+                Find out what key this is.
+
+                **Required Permissions**
+
+                Your root key must have one of the following permissions for basic key information:
+                - `api.*.read_key` (to read keys from any API)
+                - `api.<api_id>.read_key` (to read keys from a specific API)
+
+                If your rootkey lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existance of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your root key has the correct permissions.
+            operationId: whoami
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/V2KeysWhoamiRequestBody'
+                required: true
+            responses:
+                "200":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/V2KeysWhoamiResponseBody'
+                    description: |
+                        Successfully retrieved key information.
+                "400":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/BadRequestErrorResponse'
+                    description: Bad request
+                "401":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/UnauthorizedErrorResponse'
+                    description: Unauthorized
+                "403":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ForbiddenErrorResponse'
+                    description: Forbidden
+                "404":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/NotFoundErrorResponse'
+                    description: Not found
+                "500":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/InternalServerErrorResponse'
+                    description: Internal server error
+            security:
+                - rootKey: []
+            summary: Get API key by hash
+            tags:
+                - keys
+            x-speakeasy-name-override: whoami
     /v2/liveness:
         get:
             description: |

go/apps/api/openapi/openapi-split.yaml

@@ -148,6 +148,8 @@ paths:
     $ref: "./spec/paths/v2/keys/deleteKey/index.yaml"
   /v2/keys.getKey:
     $ref: "./spec/paths/v2/keys/getKey/index.yaml"
+  /v2/keys.whoami:
+    $ref: "./spec/paths/v2/keys/whoami/index.yaml"
   /v2/keys.verifyKey:
     $ref: "./spec/paths/v2/keys/verifyKey/index.yaml"
 

go/apps/api/openapi/spec/paths/v2/keys/getKey/V2KeysGetKeyRequestBody.yaml

@@ -22,21 +22,9 @@ properties:
       Use only for legitimate recovery scenarios like user password resets or emergency access.
       Most applications should keep this false to maintain security best practices and avoid accidental key exposure.
       Decryption requests are audited and may trigger security alerts in enterprise environments.
-  key:
-    type: string
-    minLength: 1
-    maxLength: 512 # Reasonable upper bound for API key strings
-    description: |
-      The complete API key string provided by you, including any prefix.
-      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: sk_1234abcdef5678
 additionalProperties: false
-oneOf:
-  - required:
-      - keyId
-  - required:
-      - key
+required:
+  - keyId
 examples:
   dashboardKeyDetails:
     summary: Dashboard key information display

go/apps/api/openapi/spec/paths/v2/keys/whoami/V2KeysWhoamiRequestBody.yaml

@@ -0,0 +1,20 @@
+type: object
+properties:
+  key:
+    type: string
+    minLength: 1
+    maxLength: 512 # Reasonable upper bound for API key strings
+    description: |
+      The complete API key string provided by you, including any prefix.
+      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: sk_1234abcdef5678
+additionalProperties: false
+required:
+  - key
+examples:
+  playground:
+    summary: Lookup by actual key string
+    description: Look up key details when provided the actual key string
+    value:
+      key: sk_1234abcdef5678