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

@@ -403,6 +403,7 @@ Methods:
 - <code title="patch /org/api_keys/{id}">client.apiKeys.<a href="./src/resources/api-keys.ts">update</a>(id, { ...params }) -> APIKey</code>
 - <code title="get /org/api_keys">client.apiKeys.<a href="./src/resources/api-keys.ts">list</a>({ ...params }) -> APIKeysOffsetPagination</code>
 - <code title="delete /org/api_keys/{id}">client.apiKeys.<a href="./src/resources/api-keys.ts">delete</a>(id) -> void</code>
+- <code title="post /org/api_keys/{id}/rotate">client.apiKeys.<a href="./src/resources/api-keys.ts">rotate</a>(id, { ...params }) -> CreatedAPIKey</code>
 
 # CredentialProviders
 

src/client.ts

@@ -24,6 +24,7 @@ import {
   APIKeyCreateParams,
   APIKeyListParams,
   APIKeyRetrieveParams,
+  APIKeyRotateParams,
   APIKeyUpdateParams,
   APIKeys,
   APIKeysOffsetPagination,
@@ -1162,6 +1163,7 @@ export declare namespace Kernel {
     type APIKeyRetrieveParams as APIKeyRetrieveParams,
     type APIKeyUpdateParams as APIKeyUpdateParams,
     type APIKeyListParams as APIKeyListParams,
+    type APIKeyRotateParams as APIKeyRotateParams,
   };
 
   export {

src/resources/api-keys.ts

@@ -88,6 +88,24 @@ export class APIKeys extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const createdAPIKey = await client.apiKeys.rotate('id');
+   * ```
+   */
+  rotate(
+    id: string,
+    body: APIKeyRotateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CreatedAPIKey> {
+    return this._client.post(path`/org/api_keys/${id}/rotate`, { body, ...options });
+  }
 }
 
 export type APIKeysOffsetPagination = OffsetPagination<APIKey>;
@@ -230,6 +248,20 @@ export interface APIKeyListParams extends OffsetPaginationParams {
   sort_direction?: 'asc' | 'desc';
 }
 
+export interface APIKeyRotateParams {
+  /**
+   * 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.
+   */
+  days_to_expire?: number | null;
+
+  /**
+   * Grace period in days before the rotated key expires. Use 0 to expire it
+   * immediately. Omit for the default grace period of 7 days.
+   */
+  expire_in_days?: number | null;
+}
+
 export declare namespace APIKeys {
   export {
     type APIKey as APIKey,
@@ -239,5 +271,6 @@ export declare namespace APIKeys {
     type APIKeyRetrieveParams as APIKeyRetrieveParams,
     type APIKeyUpdateParams as APIKeyUpdateParams,
     type APIKeyListParams as APIKeyListParams,
+    type APIKeyRotateParams as APIKeyRotateParams,
   };
 }

src/resources/index.ts

@@ -9,6 +9,7 @@ export {
   type APIKeyRetrieveParams,
   type APIKeyUpdateParams,
   type APIKeyListParams,
+  type APIKeyRotateParams,
   type APIKeysOffsetPagination,
 } from './api-keys';
 export {

tests/api-resources/api-keys.test.ts

@@ -107,4 +107,28 @@ describe('resource apiKeys', () => {
     expect(dataAndResponse.data).toBe(response);
     expect(dataAndResponse.response).toBe(rawResponse);
   });
+
+  // Mock server tests are disabled
+  test.skip('rotate', async () => {
+    const responsePromise = client.apiKeys.rotate('id');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Mock server tests are disabled
+  test.skip('rotate: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.apiKeys.rotate(
+        'id',
+        { days_to_expire: 30, expire_in_days: 7 },
+        { path: '/_stainless_unknown_path' },
+      ),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
 });