feat(api): surface deleted/expired API keys for audit trail (KERNEL-1350)

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-51549f813f3002e18c6ca8d850cc0c7932828d511c151e0412c73b6798d19e30.yml
-openapi_spec_hash: ee77b293c4bda91c1a32cfdd12b8739e
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-42074f2b600b0dc805377d6793e4bb30c959738b0f9cc44c409d094517e5e0ab.yml
+openapi_spec_hash: 81c27a833d6d9637787634180dec2abd
 config_hash: 57567e00b41af47cef1b78e51b747aa0

api.md

@@ -427,7 +427,7 @@ Response Types:
 Methods:
 
 - <code title="post /org/api_keys">client.APIKeys.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyService.New">New</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyNewParams">APIKeyNewParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#CreatedAPIKey">CreatedAPIKey</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
-- <code title="get /org/api_keys/{id}">client.APIKeys.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKey">APIKey</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code title="get /org/api_keys/{id}">client.APIKeys.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>, query <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyGetParams">APIKeyGetParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKey">APIKey</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="patch /org/api_keys/{id}">client.APIKeys.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyService.Update">Update</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>, body <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyUpdateParams">APIKeyUpdateParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKey">APIKey</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="get /org/api_keys">client.APIKeys.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, query <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyListParams">APIKeyListParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk/packages/pagination">pagination</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk/packages/pagination#OffsetPagination">OffsetPagination</a>[<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKey">APIKey</a>], <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="delete /org/api_keys/{id}">client.APIKeys.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#APIKeyService.Delete">Delete</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>

apikey.go

@@ -51,14 +51,14 @@ func (r *APIKeyService) New(ctx context.Context, body APIKeyNewParams, opts ...o
 
 // Retrieve an API key by ID for the authenticated organization. API keys are
 // masked.
-func (r *APIKeyService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *APIKey, err error) {
+func (r *APIKeyService) Get(ctx context.Context, id string, query APIKeyGetParams, opts ...option.RequestOption) (res *APIKey, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if id == "" {
 		err = errors.New("missing required id parameter")
 		return nil, err
 	}
 	path := fmt.Sprintf("org/api_keys/%s", id)
-	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...)
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
 	return res, err
 }
 
@@ -116,6 +116,9 @@ type APIKey struct {
 	// When the API key was created
 	CreatedAt time.Time       `json:"created_at" api:"required" format:"date-time"`
 	CreatedBy APIKeyCreatedBy `json:"created_by" api:"required"`
+	// When the API key was deleted (soft-deleted). Null for keys that have not been
+	// deleted.
+	DeletedAt time.Time `json:"deleted_at" api:"required" format:"date-time"`
 	// When the API key expires
 	ExpiresAt time.Time `json:"expires_at" api:"required" format:"date-time"`
 	// Masked version of the API key
@@ -127,16 +130,24 @@ type APIKey struct {
 	// Project name for project-scoped API keys. Null means the key is org-wide or the
 	// project name is unavailable.
 	ProjectName string `json:"project_name" api:"required"`
+	// Derived lifecycle status of the API key. `active` means usable. `expired` means
+	// past its expires_at. `deleted` means it was deleted (soft-deleted) and can no
+	// longer authenticate. Deleted takes precedence over expired.
+	//
+	// Any of "active", "expired", "deleted".
+	Status APIKeyStatus `json:"status" api:"required"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
 	JSON struct {
 		ID          respjson.Field
 		CreatedAt   respjson.Field
 		CreatedBy   respjson.Field
+		DeletedAt   respjson.Field
 		ExpiresAt   respjson.Field
 		MaskedKey   respjson.Field
 		Name        respjson.Field
 		ProjectID   respjson.Field
 		ProjectName respjson.Field
+		Status      respjson.Field
 		ExtraFields map[string]respjson.Field
 		raw         string
 	} `json:"-"`
@@ -171,6 +182,17 @@ func (r *APIKeyCreatedBy) UnmarshalJSON(data []byte) error {
 	return apijson.UnmarshalRoot(data, r)
 }
 
+// Derived lifecycle status of the API key. `active` means usable. `expired` means
+// past its expires_at. `deleted` means it was deleted (soft-deleted) and can no
+// longer authenticate. Deleted takes precedence over expired.
+type APIKeyStatus string
+
+const (
+	APIKeyStatusActive  APIKeyStatus = "active"
+	APIKeyStatusExpired APIKeyStatus = "expired"
+	APIKeyStatusDeleted APIKeyStatus = "deleted"
+)
+
 // API key returned immediately after creation. Includes the plaintext key once.
 type CreatedAPIKey struct {
 	// Plaintext API key. Only returned once when the key is created.
@@ -208,6 +230,21 @@ func (r *APIKeyNewParams) UnmarshalJSON(data []byte) error {
 	return apijson.UnmarshalRoot(data, r)
 }
 
+type APIKeyGetParams struct {
+	// When true, return the API key even if it has been deleted (soft-deleted), for
+	// audit purposes. Defaults to false, which returns 404 for a deleted key.
+	IncludeDeleted param.Opt[bool] `query:"include_deleted,omitzero" json:"-"`
+	paramObj
+}
+
+// URLQuery serializes [APIKeyGetParams]'s query parameters as `url.Values`.
+func (r APIKeyGetParams) URLQuery() (v url.Values, err error) {
+	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
+		ArrayFormat:  apiquery.ArrayQueryFormatComma,
+		NestedFormat: apiquery.NestedQueryFormatBrackets,
+	})
+}
+
 type APIKeyUpdateParams struct {
 	// New API key name
 	Name string `json:"name" api:"required"`
@@ -223,6 +260,9 @@ func (r *APIKeyUpdateParams) UnmarshalJSON(data []byte) error {
 }
 
 type APIKeyListParams struct {
+	// When true, include deleted (soft-deleted) API keys in the results for audit
+	// purposes. Defaults to false, which returns only live keys.
+	IncludeDeleted param.Opt[bool] `query:"include_deleted,omitzero" json:"-"`
 	// Maximum number of results to return
 	Limit param.Opt[int64] `query:"limit,omitzero" json:"-"`
 	// Number of results to skip

apikey_test.go

@@ -40,7 +40,7 @@ func TestAPIKeyNewWithOptionalParams(t *testing.T) {
 	}
 }
 
-func TestAPIKeyGet(t *testing.T) {
+func TestAPIKeyGetWithOptionalParams(t *testing.T) {
 	t.Skip("Mock server tests are disabled")
 	baseURL := "http://localhost:4010"
 	if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok {
@@ -53,7 +53,13 @@ func TestAPIKeyGet(t *testing.T) {
 		option.WithBaseURL(baseURL),
 		option.WithAPIKey("My API Key"),
 	)
-	_, err := client.APIKeys.Get(context.TODO(), "id")
+	_, err := client.APIKeys.Get(
+		context.TODO(),
+		"id",
+		kernel.APIKeyGetParams{
+			IncludeDeleted: kernel.Bool(true),
+		},
+	)
 	if err != nil {
 		var apierr *kernel.Error
 		if errors.As(err, &apierr) {
@@ -106,11 +112,12 @@ func TestAPIKeyListWithOptionalParams(t *testing.T) {
 		option.WithAPIKey("My API Key"),
 	)
 	_, err := client.APIKeys.List(context.TODO(), kernel.APIKeyListParams{
-		Limit:         kernel.Int(100),
-		Offset:        kernel.Int(0),
-		Query:         kernel.String("query"),
-		SortBy:        kernel.APIKeyListParamsSortByCreatedAt,
-		SortDirection: kernel.APIKeyListParamsSortDirectionAsc,
+		IncludeDeleted: kernel.Bool(true),
+		Limit:          kernel.Int(100),
+		Offset:         kernel.Int(0),
+		Query:          kernel.String("query"),
+		SortBy:         kernel.APIKeyListParamsSortByCreatedAt,
+		SortDirection:  kernel.APIKeyListParamsSortDirectionAsc,
 	})
 	if err != nil {
 		var apierr *kernel.Error