From 4b4ebdb51a6c18e6c63b32c4a5abeaba0435ae74 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 24 Jun 2026 15:41:18 -0500 Subject: [PATCH 1/4] Draft changes Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/catalog/apis.md | 66 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/app/catalog/apis.md b/app/catalog/apis.md index a6be85e2c00..983260b365d 100644 --- a/app/catalog/apis.md +++ b/app/catalog/apis.md @@ -577,6 +577,7 @@ rows: details: | * Developers can select servers from a list with support for server variables (templated server URLs). * Security scheme rendering (for example, API key and OAuth2 flows). + * Sensitive data masking: auth credentials from `securitySchemes` are masked automatically in code samples and Try It response headers. Annotate body properties with `x-sensitive-data` for additional masking. - feature: AsyncAPI details: | * Supports channels, operations, and messages/payloads. @@ -588,6 +589,71 @@ rows: * Collapsible sections. You can choose either **previous** and **next** navigation buttons or continuous scrolling. {% endtable %} +### Protect sensitive data in your API docs + +If your spec includes example values for fields like passwords, API keys, or email addresses, you can prevent those values from appearing in generated code samples, spec examples, and Try It responses. + +* **Automatic masking:** Authentication credentials from `securitySchemes` are masked automatically in code samples and Try It response headers. No annotation is needed. +* **Opt-in masking with `x-sensitive-data`:** For request and response body properties that contain sensitive values, add `x-sensitive-data` to the schema property. This controls how the value is displayed in code sample examples and Try It response bodies. + +The following mask strategies are available: + +{% table %} +columns: + - title: Strategy + key: strategy + - title: Displayed as + key: display + - title: When to use + key: use +rows: + - strategy: "`full`" + display: "`••••••`" + use: Hide the value entirely + - strategy: "`remove`" + display: "*(field omitted)*" + use: Remove the field from examples + - strategy: "`hash`" + display: "`3d2a1f8c`" + use: Show that two values are equal without revealing either + - strategy: "`regex`" + display: "Partial mask (for example, `••••••@example.com`)" + use: Mask only part of the value, using a regex pattern +{% endtable %} + +The following example shows how you can use `x-sensitive-data` in a schema: + +```yaml +components: + schemas: + LoginRequest: + type: object + properties: + username: + type: string + example: alice + password: + type: string + x-sensitive-data: + mask: full # displayed as •••••• + email: + type: string + x-sensitive-data: + mask: regex + pattern: ^[^@]+ # displayed as ••••••@example.com + apiToken: + type: string + x-sensitive-data: + mask: remove # field omitted from examples entirely +``` + +{:.info} +> Masking is display-only. Try It always sends the real credential values so API calls work correctly. + +#### Mask sensitive data toggle + +Any panel that contains masked data shows a **Mask sensitive data** toggle, which is on by default. Developers can turn it off to see the real values inline without leaving the page. The toggle is hidden when no masking is active for that panel. + ### Filtering published APIs in {{site.dev_portal}} You can filter and categorize published APIs on your {{site.dev_portal}}s with custom attributes. By assigning attributes to an API, this allows users to filter APIs in the {{site.dev_portal}} sidebar. For an API, you can define one or more custom attributes, and each attribute can have one or more values. For example, if you had a Billing API, you could label it with `"visibility": ["Internal"]` and `"platform": ["Web", "Mobile"]`. From c76c5f4ab1b98dbc73a2322c2f5ed2c96481dcdb Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 25 Jun 2026 09:03:49 -0500 Subject: [PATCH 2/4] Apply suggestions from copilot Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- app/catalog/apis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/catalog/apis.md b/app/catalog/apis.md index 983260b365d..9e03a5b7b2c 100644 --- a/app/catalog/apis.md +++ b/app/catalog/apis.md @@ -594,7 +594,7 @@ rows: If your spec includes example values for fields like passwords, API keys, or email addresses, you can prevent those values from appearing in generated code samples, spec examples, and Try It responses. * **Automatic masking:** Authentication credentials from `securitySchemes` are masked automatically in code samples and Try It response headers. No annotation is needed. -* **Opt-in masking with `x-sensitive-data`:** For request and response body properties that contain sensitive values, add `x-sensitive-data` to the schema property. This controls how the value is displayed in code sample examples and Try It response bodies. +* **Opt-in masking with `x-sensitive-data`:** For request and response body properties that contain sensitive values, add `x-sensitive-data` to the schema property. This controls how the value is displayed in code samples and Try It response bodies. The following mask strategies are available: @@ -648,7 +648,7 @@ components: ``` {:.info} -> Masking is display-only. Try It always sends the real credential values so API calls work correctly. +> Masking is display-only: Try It sends the underlying (unmasked) values so API calls work correctly. Do not include real secrets in your spec examples. #### Mask sensitive data toggle From 4def726ab6dda66211361b28ec70d0280ee5c7c7 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 30 Jun 2026 08:50:54 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- app/catalog/apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/catalog/apis.md b/app/catalog/apis.md index 9e03a5b7b2c..cd02a44a29e 100644 --- a/app/catalog/apis.md +++ b/app/catalog/apis.md @@ -604,7 +604,7 @@ columns: key: strategy - title: Displayed as key: display - - title: When to use + - title: "Use when you want to..." key: use rows: - strategy: "`full`" From 23bd1cd7aaedb54b521ab723515cc8f801940ffb Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 30 Jun 2026 08:54:31 -0500 Subject: [PATCH 4/4] describe auto masking Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/catalog/apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/catalog/apis.md b/app/catalog/apis.md index cd02a44a29e..026e1019145 100644 --- a/app/catalog/apis.md +++ b/app/catalog/apis.md @@ -593,7 +593,7 @@ rows: If your spec includes example values for fields like passwords, API keys, or email addresses, you can prevent those values from appearing in generated code samples, spec examples, and Try It responses. -* **Automatic masking:** Authentication credentials from `securitySchemes` are masked automatically in code samples and Try It response headers. No annotation is needed. +* **Automatic masking:** Authentication credentials from `securitySchemes` are masked automatically in code samples and Try It response headers. They are masked like `full` where the value will display as `••••••` in the UI. No annotation is needed. * **Opt-in masking with `x-sensitive-data`:** For request and response body properties that contain sensitive values, add `x-sensitive-data` to the schema property. This controls how the value is displayed in code samples and Try It response bodies. The following mask strategies are available: