feat: Add API key rotate endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 119
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-c98841235b0ece0591f28f7dd424339b6ef2f3e8f539b95b670ae0da2ef43df4.yml
-openapi_spec_hash: c1e9456765f0743a333af297d135d5cf
-config_hash: 57567e00b41af47cef1b78e51b747aa0
+configured_endpoints: 120
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-1f10598afa01d76d22b0ed63685248f482f74c9353cffe1d3e4a3d38da7716cf.yml
+openapi_spec_hash: 8936f458bfa681b709e459ca1cc76fb5
+config_hash: 03c7e57f268c750e2415831662e95969

api.md

@@ -453,6 +453,7 @@ Methods:
 - <code title="patch /org/api_keys/{id}">client.api_keys.<a href="./src/kernel/resources/api_keys.py">update</a>(id, \*\*<a href="src/kernel/types/api_key_update_params.py">params</a>) -> <a href="./src/kernel/types/api_key.py">APIKey</a></code>
 - <code title="get /org/api_keys">client.api_keys.<a href="./src/kernel/resources/api_keys.py">list</a>(\*\*<a href="src/kernel/types/api_key_list_params.py">params</a>) -> <a href="./src/kernel/types/api_key.py">SyncOffsetPagination[APIKey]</a></code>
 - <code title="delete /org/api_keys/{id}">client.api_keys.<a href="./src/kernel/resources/api_keys.py">delete</a>(id) -> None</code>
+- <code title="post /org/api_keys/{id}/rotate">client.api_keys.<a href="./src/kernel/resources/api_keys.py">rotate</a>(id, \*\*<a href="src/kernel/types/api_key_rotate_params.py">params</a>) -> <a href="./src/kernel/types/created_api_key.py">CreatedAPIKey</a></code>
 
 # CredentialProviders
 

src/kernel/resources/api_keys.py

@@ -7,7 +7,13 @@
 
 import httpx
 
-from ..types import api_key_list_params, api_key_create_params, api_key_update_params, api_key_retrieve_params
+from ..types import (
+    api_key_list_params,
+    api_key_create_params,
+    api_key_rotate_params,
+    api_key_update_params,
+    api_key_retrieve_params,
+)
 from .._types import Body, Omit, Query, Headers, NoneType, NotGiven, omit, not_given
 from .._utils import path_template, maybe_transform, async_maybe_transform
 from .._compat import cached_property
@@ -277,6 +283,57 @@ def delete(
             cast_to=NoneType,
         )
 
+    def rotate(
+        self,
+        id: str,
+        *,
+        days_to_expire: Optional[int] | Omit = omit,
+        expire_in_days: Optional[int] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> CreatedAPIKey:
+        """Rotate an API key.
+
+        Issues a new key that copies the name and project of the
+        rotated key, and schedules the rotated key to expire after a grace period so
+        in-flight callers can swap over. The new plaintext key is returned once.
+
+        Args:
+          days_to_expire: Lifetime in days for the new key, up to 3650. Omit to reuse the rotated key's
+              original lifetime, or never-expires if it had none.
+
+          expire_in_days: Grace period in days before the rotated key expires. Use 0 to expire it
+              immediately. Omit for the default grace period of 7 days.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._post(
+            path_template("/org/api_keys/{id}/rotate", id=id),
+            body=maybe_transform(
+                {
+                    "days_to_expire": days_to_expire,
+                    "expire_in_days": expire_in_days,
+                },
+                api_key_rotate_params.APIKeyRotateParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=CreatedAPIKey,
+        )
+
 
 class AsyncAPIKeysResource(AsyncAPIResource):
     """Create and manage API keys for organization and project-scoped access."""
@@ -529,6 +586,57 @@ async def delete(
             cast_to=NoneType,
         )
 
+    async def rotate(
+        self,
+        id: str,
+        *,
+        days_to_expire: Optional[int] | Omit = omit,
+        expire_in_days: Optional[int] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> CreatedAPIKey:
+        """Rotate an API key.
+
+        Issues a new key that copies the name and project of the
+        rotated key, and schedules the rotated key to expire after a grace period so
+        in-flight callers can swap over. The new plaintext key is returned once.
+
+        Args:
+          days_to_expire: Lifetime in days for the new key, up to 3650. Omit to reuse the rotated key's
+              original lifetime, or never-expires if it had none.
+
+          expire_in_days: Grace period in days before the rotated key expires. Use 0 to expire it
+              immediately. Omit for the default grace period of 7 days.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return await self._post(
+            path_template("/org/api_keys/{id}/rotate", id=id),
+            body=await async_maybe_transform(
+                {
+                    "days_to_expire": days_to_expire,
+                    "expire_in_days": expire_in_days,
+                },
+                api_key_rotate_params.APIKeyRotateParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=CreatedAPIKey,
+        )
+
 
 class APIKeysResourceWithRawResponse:
     def __init__(self, api_keys: APIKeysResource) -> None:
@@ -549,6 +657,9 @@ def __init__(self, api_keys: APIKeysResource) -> None:
         self.delete = to_raw_response_wrapper(
             api_keys.delete,
         )
+        self.rotate = to_raw_response_wrapper(
+            api_keys.rotate,
+        )
 
 
 class AsyncAPIKeysResourceWithRawResponse:
@@ -570,6 +681,9 @@ def __init__(self, api_keys: AsyncAPIKeysResource) -> None:
         self.delete = async_to_raw_response_wrapper(
             api_keys.delete,
         )
+        self.rotate = async_to_raw_response_wrapper(
+            api_keys.rotate,
+        )
 
 
 class APIKeysResourceWithStreamingResponse:
@@ -591,6 +705,9 @@ def __init__(self, api_keys: APIKeysResource) -> None:
         self.delete = to_streamed_response_wrapper(
             api_keys.delete,
         )
+        self.rotate = to_streamed_response_wrapper(
+            api_keys.rotate,
+        )
 
 
 class AsyncAPIKeysResourceWithStreamingResponse:
@@ -612,3 +729,6 @@ def __init__(self, api_keys: AsyncAPIKeysResource) -> None:
         self.delete = async_to_streamed_response_wrapper(
             api_keys.delete,
         )
+        self.rotate = async_to_streamed_response_wrapper(
+            api_keys.rotate,
+        )

src/kernel/types/__init__.py

@@ -39,6 +39,7 @@
 from .proxy_list_response import ProxyListResponse as ProxyListResponse
 from .proxy_check_response import ProxyCheckResponse as ProxyCheckResponse
 from .api_key_create_params import APIKeyCreateParams as APIKeyCreateParams
+from .api_key_rotate_params import APIKeyRotateParams as APIKeyRotateParams
 from .api_key_update_params import APIKeyUpdateParams as APIKeyUpdateParams
 from .browser_create_params import BrowserCreateParams as BrowserCreateParams
 from .browser_curl_response import BrowserCurlResponse as BrowserCurlResponse

src/kernel/types/api_key_rotate_params.py

@@ -0,0 +1,23 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Optional
+from typing_extensions import TypedDict
+
+__all__ = ["APIKeyRotateParams"]
+
+
+class APIKeyRotateParams(TypedDict, total=False):
+    days_to_expire: Optional[int]
+    """Lifetime in days for the new key, up to 3650.
+
+    Omit to reuse the rotated key's original lifetime, or never-expires if it had
+    none.
+    """
+
+    expire_in_days: Optional[int]
+    """Grace period in days before the rotated key expires.
+
+    Use 0 to expire it immediately. Omit for the default grace period of 7 days.
+    """

tests/api_resources/test_api_keys.py

@@ -245,6 +245,58 @@ def test_path_params_delete(self, client: Kernel) -> None:
                 "",
             )
 
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_method_rotate(self, client: Kernel) -> None:
+        api_key = client.api_keys.rotate(
+            id="id",
+        )
+        assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_method_rotate_with_all_params(self, client: Kernel) -> None:
+        api_key = client.api_keys.rotate(
+            id="id",
+            days_to_expire=30,
+            expire_in_days=7,
+        )
+        assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_raw_response_rotate(self, client: Kernel) -> None:
+        response = client.api_keys.with_raw_response.rotate(
+            id="id",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        api_key = response.parse()
+        assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_streaming_response_rotate(self, client: Kernel) -> None:
+        with client.api_keys.with_streaming_response.rotate(
+            id="id",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            api_key = response.parse()
+            assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_path_params_rotate(self, client: Kernel) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
+            client.api_keys.with_raw_response.rotate(
+                id="",
+            )
+
 
 class TestAsyncAPIKeys:
     parametrize = pytest.mark.parametrize(
@@ -474,3 +526,55 @@ async def test_path_params_delete(self, async_client: AsyncKernel) -> None:
             await async_client.api_keys.with_raw_response.delete(
                 "",
             )
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_method_rotate(self, async_client: AsyncKernel) -> None:
+        api_key = await async_client.api_keys.rotate(
+            id="id",
+        )
+        assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_method_rotate_with_all_params(self, async_client: AsyncKernel) -> None:
+        api_key = await async_client.api_keys.rotate(
+            id="id",
+            days_to_expire=30,
+            expire_in_days=7,
+        )
+        assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_raw_response_rotate(self, async_client: AsyncKernel) -> None:
+        response = await async_client.api_keys.with_raw_response.rotate(
+            id="id",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        api_key = await response.parse()
+        assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_streaming_response_rotate(self, async_client: AsyncKernel) -> None:
+        async with async_client.api_keys.with_streaming_response.rotate(
+            id="id",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            api_key = await response.parse()
+            assert_matches_type(CreatedAPIKey, api_key, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_path_params_rotate(self, async_client: AsyncKernel) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
+            await async_client.api_keys.with_raw_response.rotate(
+                id="",
+            )