release: 0.4.0

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 10
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/keycard-api-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
       - uses: actions/checkout@v6
 
@@ -35,7 +35,7 @@ jobs:
         run: ./scripts/lint
 
   build:
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     timeout-minutes: 10
     name: build
     permissions:

.gitignore

@@ -1,4 +1,5 @@
 .prism.log
+.stdy.log
 _dev
 
 __pycache__

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.0"
+  ".": "0.4.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 107
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/keycard%2Fkeycard-api-e0b7b296f7b0cac79675a790974f3ad90eb46833027467ee97c3ed21675628b8.yml
-openapi_spec_hash: 5e60faefb18dd2fca721f14252ab907a
-config_hash: dbb3c94874836d520e64fc8ffda4f0d3
+configured_endpoints: 106
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/keycard%2Fkeycard-api-932699a5ea16b4d5c8f2e2f12dfe48e56d0eaefa58ea18799147582bfa8d093b.yml
+openapi_spec_hash: 7a1bede6d87265f841a08b65cd3f87e1
+config_hash: 8fdc6a9c1185417459f79052b1222ff0

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.4.0 (2026-04-17)
+
+Full Changelog: [v0.3.0...v0.4.0](https://github.com/keycardai/keycard-python/compare/v0.3.0...v0.4.0)
+
+### Features
+
+* add email search to list organization identities endpoint ([f9b2707](https://github.com/keycardai/keycard-python/commit/f9b2707b0649678407423d2f5b3007a6d7bcc2e6))
+* add openapi-yaml command ([b37854a](https://github.com/keycardai/keycard-python/commit/b37854a0910db1c34df7509b706c34306a160ebf))
+* add owner_type and enforce protection for platform-owned versions (ACC-29) ([bfac76d](https://github.com/keycardai/keycard-python/commit/bfac76da47db6264d00d9df73c387a8e5e175840))
+* add PRM discovery to MCP gateway endpoint ([fbc502d](https://github.com/keycardai/keycard-python/commit/fbc502dc075d7a0f6890317fc59203ca51d644a7))
+* improved identities pagination ([d4c4d1b](https://github.com/keycardai/keycard-python/commit/d4c4d1ba4d76d709e6067d36f1848d293d227a81))
+* **internal:** implement indices array format for query and form serialization ([617099d](https://github.com/keycardai/keycard-python/commit/617099df6ed00538530a5f4ed285130dd5ac13c7))
+* normalize and validate user input (ACC-107) ([7bb7c97](https://github.com/keycardai/keycard-python/commit/7bb7c970e37b50353c54b4afc6307608c5bcdd94))
+* provide more context for policy schema ([46bea8a](https://github.com/keycardai/keycard-python/commit/46bea8a4493318b0b37904119e057cb7b4e50550))
+* shadow testing (ACC-14) ([f8f9ac8](https://github.com/keycardai/keycard-python/commit/f8f9ac8089531b5613cb9147dd736de348de2d33))
+* Support for user identifier and provider user identifier claim ([ac47cc2](https://github.com/keycardai/keycard-python/commit/ac47cc20c48168e226a78d5402d7f8e745881bb8))
+
+
+### Bug Fixes
+
+* **client:** preserve hardcoded query params when merging with user params ([3a94db2](https://github.com/keycardai/keycard-python/commit/3a94db26d731d5d0a34957d0aec691b0346eb275))
+* ensure file data are only sent as 1 parameter ([bcc62f9](https://github.com/keycardai/keycard-python/commit/bcc62f9c4cd18748dc5a26eb4d84fee22573a237))
+* sanitize endpoint path params ([6993e56](https://github.com/keycardai/keycard-python/commit/6993e56d5e9a79713471a0b2b33920c1e2da77d9))
+
+
+### Performance Improvements
+
+* **client:** optimize file structure copying in multipart requests ([2b5cca8](https://github.com/keycardai/keycard-python/commit/2b5cca867abc3dd0171c465ec056bfff88cd8f81))
+
+
+### Chores
+
+* **ci:** skip lint on metadata-only changes ([bc52e3f](https://github.com/keycardai/keycard-python/commit/bc52e3f59616d0754b7f0bc30374fac7f357f63b))
+* **internal:** update gitignore ([24f9a15](https://github.com/keycardai/keycard-python/commit/24f9a15a6031769c2a5912a3eda480fb82fc17b1))
+
 ## 0.3.0 (2026-03-16)
 
 Full Changelog: [v0.2.0...v0.3.0](https://github.com/keycardai/keycard-python/compare/v0.2.0...v0.3.0)

README.md

@@ -9,15 +9,6 @@ and offers both synchronous and asynchronous clients powered by [httpx](https://
 
 It is generated with [Stainless](https://www.stainless.com/).
 
-## MCP Server
-
-Use the Keycard API MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
-
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40keycardai%2Fapi-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBrZXljYXJkYWkvYXBpLW1jcCJdLCJlbnYiOnsiS0VZQ0FSRF9BUElfQVBJX0tFWSI6Ik15IEFQSSBLZXkiLCJLRVlDQVJEX0FQSV9DTElFTlRfSUQiOiJNeSBDbGllbnQgSUQiLCJLRVlDQVJEX0FQSV9DTElFTlRfU0VDUkVUIjoiTXkgQ2xpZW50IFNlY3JldCJ9fQ)
-[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40keycardai%2Fapi-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40keycardai%2Fapi-mcp%22%5D%2C%22env%22%3A%7B%22KEYCARD_API_API_KEY%22%3A%22My%20API%20Key%22%2C%22KEYCARD_API_CLIENT_ID%22%3A%22My%20Client%20ID%22%2C%22KEYCARD_API_CLIENT_SECRET%22%3A%22My%20Client%20Secret%22%7D%7D)
-
-> Note: You may need to set environment variables in your MCP client.
-
 ## Documentation
 
 The REST API documentation can be found on [docs.keycard.ai](https://docs.keycard.ai). The full API of this library can be found in [api.md](api.md).

api.md

@@ -8,7 +8,6 @@ from keycardai_api.types import (
     PageInfoPagination,
     Zone,
     ZoneListResponse,
-    ZoneListSessionResourceAccessResponse,
 )
 ```
 
@@ -19,7 +18,6 @@ Methods:
 - <code title="patch /zones/{zoneId}">client.zones.<a href="./src/keycardai_api/resources/zones/zones.py">update</a>(zone_id, \*\*<a href="src/keycardai_api/types/zone_update_params.py">params</a>) -> <a href="./src/keycardai_api/types/zone.py">Zone</a></code>
 - <code title="get /zones">client.zones.<a href="./src/keycardai_api/resources/zones/zones.py">list</a>(\*\*<a href="src/keycardai_api/types/zone_list_params.py">params</a>) -> <a href="./src/keycardai_api/types/zone_list_response.py">ZoneListResponse</a></code>
 - <code title="delete /zones/{zoneId}">client.zones.<a href="./src/keycardai_api/resources/zones/zones.py">delete</a>(zone_id) -> None</code>
-- <code title="get /zones/{zoneId}/session-resource-access">client.zones.<a href="./src/keycardai_api/resources/zones/zones.py">list_session_resource_access</a>(zone_id, \*\*<a href="src/keycardai_api/types/zone_list_session_resource_access_params.py">params</a>) -> <a href="./src/keycardai_api/types/zone_list_session_resource_access_response.py">ZoneListSessionResourceAccessResponse</a></code>
 
 ## Applications
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "keycardai_api"
-version = "0.3.0"
+version = "0.4.0"
 description = "The official Python library for the keycard-api API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/keycardai_api/_base_client.py

@@ -558,6 +558,10 @@ def _build_request(
                 files = cast(HttpxRequestFiles, ForceMultipartDict())
 
         prepared_url = self._prepare_url(options.url)
+        # preserve hard-coded query params from the url
+        if params and prepared_url.query:
+            params = {**dict(prepared_url.params.items()), **params}
+            prepared_url = prepared_url.copy_with(raw_path=prepared_url.raw_path.split(b"?", 1)[0])
         if "_" in prepared_url.host:
             # work around https://github.com/encode/httpx/discussions/2880
             kwargs["extensions"] = {"sni_hostname": prepared_url.host.replace("_", "-")}

src/keycardai_api/_files.py

@@ -3,8 +3,8 @@
 import io
 import os
 import pathlib
-from typing import overload
-from typing_extensions import TypeGuard
+from typing import Sequence, cast, overload
+from typing_extensions import TypeVar, TypeGuard
 
 import anyio
 
@@ -17,7 +17,9 @@
     HttpxFileContent,
     HttpxRequestFiles,
 )
-from ._utils import is_tuple_t, is_mapping_t, is_sequence_t
+from ._utils import is_list, is_mapping, is_tuple_t, is_mapping_t, is_sequence_t
+
+_T = TypeVar("_T")
 
 
 def is_base64_file_input(obj: object) -> TypeGuard[Base64FileInput]:
@@ -121,3 +123,51 @@ async def async_read_file_content(file: FileContent) -> HttpxFileContent:
         return await anyio.Path(file).read_bytes()
 
     return file
+
+
+def deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]]) -> _T:
+    """Copy only the containers along the given paths.
+
+    Used to guard against mutation by extract_files without copying the entire structure.
+    Only dicts and lists that lie on a path are copied; everything else
+    is returned by reference.
+
+    For example, given paths=[["foo", "files", "file"]] and the structure:
+        {
+            "foo": {
+                "bar": {"baz": {}},
+                "files": {"file": <content>}
+            }
+        }
+    The root dict, "foo", and "files" are copied (they lie on the path).
+    "bar" and "baz" are returned by reference (off the path).
+    """
+    return _deepcopy_with_paths(item, paths, 0)
+
+
+def _deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]], index: int) -> _T:
+    if not paths:
+        return item
+    if is_mapping(item):
+        key_to_paths: dict[str, list[Sequence[str]]] = {}
+        for path in paths:
+            if index < len(path):
+                key_to_paths.setdefault(path[index], []).append(path)
+
+        # if no path continues through this mapping, it won't be mutated and copying it is redundant
+        if not key_to_paths:
+            return item
+
+        result = dict(item)
+        for key, subpaths in key_to_paths.items():
+            if key in result:
+                result[key] = _deepcopy_with_paths(result[key], subpaths, index + 1)
+        return cast(_T, result)
+    if is_list(item):
+        array_paths = [path for path in paths if index < len(path) and path[index] == "<array>"]
+
+        # if no path expects a list here, nothing will be mutated inside it - return by reference
+        if not array_paths:
+            return cast(_T, item)
+        return cast(_T, [_deepcopy_with_paths(entry, array_paths, index + 1) for entry in item])
+    return item

src/keycardai_api/_qs.py

@@ -101,7 +101,10 @@ def _stringify_item(
                     items.extend(self._stringify_item(key, item, opts))
                 return items
             elif array_format == "indices":
-                raise NotImplementedError("The array indices format is not supported yet")
+                items = []
+                for i, item in enumerate(value):
+                    items.extend(self._stringify_item(f"{key}[{i}]", item, opts))
+                return items
             elif array_format == "brackets":
                 items = []
                 key = key + "[]"

src/keycardai_api/_utils/__init__.py

@@ -1,3 +1,4 @@
+from ._path import path_template as path_template
 from ._sync import asyncify as asyncify
 from ._proxy import LazyProxy as LazyProxy
 from ._utils import (
@@ -23,7 +24,6 @@
     coerce_integer as coerce_integer,
     file_from_path as file_from_path,
     strip_not_given as strip_not_given,
-    deepcopy_minimal as deepcopy_minimal,
     get_async_library as get_async_library,
     maybe_coerce_float as maybe_coerce_float,
     get_required_header as get_required_header,

src/keycardai_api/_utils/_path.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import re
+from typing import (
+    Any,
+    Mapping,
+    Callable,
+)
+from urllib.parse import quote
+
+# Matches '.' or '..' where each dot is either literal or percent-encoded (%2e / %2E).
+_DOT_SEGMENT_RE = re.compile(r"^(?:\.|%2[eE]){1,2}$")
+
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+def _quote_path_segment_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI path segment.
+
+    Considers characters not in `pchar` set from RFC 3986 §3.3 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+    """
+    # quote() already treats unreserved characters (letters, digits, and -._~)
+    # as safe, so we only need to add sub-delims, ':', and '@'.
+    # Notably, unlike the default `safe` for quote(), / is unsafe and must be quoted.
+    return quote(value, safe="!$&'()*+,;=:@")
+
+
+def _quote_query_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI query string.
+
+    Considers &, = and characters not in `query` set from RFC 3986 §3.4 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.4
+    """
+    return quote(value, safe="!$'()*+,;:@/?")
+
+
+def _quote_fragment_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI fragment.
+
+    Considers characters not in `fragment` set from RFC 3986 §3.5 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.5
+    """
+    return quote(value, safe="!$&'()*+,;=:@/?")
+
+
+def _interpolate(
+    template: str,
+    values: Mapping[str, Any],
+    quoter: Callable[[str], str],
+) -> str:
+    """Replace {name} placeholders in `template`, quoting each value with `quoter`.
+
+    Placeholder names are looked up in `values`.
+
+    Raises:
+        KeyError: If a placeholder is not found in `values`.
+    """
+    # re.split with a capturing group returns alternating
+    # [text, name, text, name, ..., text] elements.
+    parts = _PLACEHOLDER_RE.split(template)
+
+    for i in range(1, len(parts), 2):
+        name = parts[i]
+        if name not in values:
+            raise KeyError(f"a value for placeholder {{{name}}} was not provided")
+        val = values[name]
+        if val is None:
+            parts[i] = "null"
+        elif isinstance(val, bool):
+            parts[i] = "true" if val else "false"
+        else:
+            parts[i] = quoter(str(values[name]))
+
+    return "".join(parts)
+
+
+def path_template(template: str, /, **kwargs: Any) -> str:
+    """Interpolate {name} placeholders in `template` from keyword arguments.
+
+    Args:
+        template: The template string containing {name} placeholders.
+        **kwargs: Keyword arguments to interpolate into the template.
+
+    Returns:
+        The template with placeholders interpolated and percent-encoded.
+
+        Safe characters for percent-encoding are dependent on the URI component.
+        Placeholders in path and fragment portions are percent-encoded where the `segment`
+        and `fragment` sets from RFC 3986 respectively are considered safe.
+        Placeholders in the query portion are percent-encoded where the `query` set from
+        RFC 3986 §3.3 is considered safe except for = and & characters.
+
+    Raises:
+        KeyError: If a placeholder is not found in `kwargs`.
+        ValueError: If resulting path contains /./ or /../ segments (including percent-encoded dot-segments).
+    """
+    # Split the template into path, query, and fragment portions.
+    fragment_template: str | None = None
+    query_template: str | None = None
+
+    rest = template
+    if "#" in rest:
+        rest, fragment_template = rest.split("#", 1)
+    if "?" in rest:
+        rest, query_template = rest.split("?", 1)
+    path_template = rest
+
+    # Interpolate each portion with the appropriate quoting rules.
+    path_result = _interpolate(path_template, kwargs, _quote_path_segment_part)
+
+    # Reject dot-segments (. and ..) in the final assembled path.  The check
+    # runs after interpolation so that adjacent placeholders or a mix of static
+    # text and placeholders that together form a dot-segment are caught.
+    # Also reject percent-encoded dot-segments to protect against incorrectly
+    # implemented normalization in servers/proxies.
+    for segment in path_result.split("/"):
+        if _DOT_SEGMENT_RE.match(segment):
+            raise ValueError(f"Constructed path {path_result!r} contains dot-segment {segment!r} which is not allowed")
+
+    result = path_result
+    if query_template is not None:
+        result += "?" + _interpolate(query_template, kwargs, _quote_query_part)
+    if fragment_template is not None:
+        result += "#" + _interpolate(fragment_template, kwargs, _quote_fragment_part)
+
+    return result

src/keycardai_api/_utils/_utils.py

@@ -86,8 +86,9 @@ def _extract_items(
     index += 1
     if is_dict(obj):
         try:
-            # We are at the last entry in the path so we must remove the field
-            if (len(path)) == index:
+            # Remove the field if there are no more dict keys in the path,
+            # only "<array>" traversal markers or end.
+            if all(p == "<array>" for p in path[index:]):
                 item = obj.pop(key)
             else:
                 item = obj[key]
@@ -176,21 +177,6 @@ def is_iterable(obj: object) -> TypeGuard[Iterable[object]]:
     return isinstance(obj, Iterable)
 
 
-def deepcopy_minimal(item: _T) -> _T:
-    """Minimal reimplementation of copy.deepcopy() that will only copy certain object types:
-
-    - mappings, e.g. `dict`
-    - list
-
-    This is done for performance reasons.
-    """
-    if is_mapping(item):
-        return cast(_T, {k: deepcopy_minimal(v) for k, v in item.items()})
-    if is_list(item):
-        return cast(_T, [deepcopy_minimal(entry) for entry in item])
-    return item
-
-
 # copied from https://github.com/Rapptz/RoboDanny
 def human_join(seq: Sequence[str], *, delim: str = ", ", final: str = "or") -> str:
     size = len(seq)

src/keycardai_api/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "keycardai_api"
-__version__ = "0.3.0"  # x-release-please-version
+__version__ = "0.4.0"  # x-release-please-version