From b8a64aa8c599a11b0ba84530286e29456102864a Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Wed, 21 Oct 2026 12:38:24 +0100 Subject: [PATCH 1/2] Document scopes and errors for Brands and IP allowlist operations - List and retrieve brands: state the required `read_brands` OAuth scope and add a token_unauthorized 401 example for a token without it. Complete the truncated default-brand sentence. - Retrieve brand: the 404 error code is `brand_not_found`. - Get and update IP allowlist: state the required `manage_ip_allowlist` OAuth scope and add a token_unauthorized 401 example. - Update IP allowlist: both fields are optional, omitted fields are left unchanged, and entries must be IPv4 addresses or IPv4 CIDR ranges. Applied to both 2.17 and Preview where the operation exists. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 41 ++++++++++++++-- descriptions/2.17/api.intercom.io.yaml | 66 ++++++++++++++++++++++++-- 2 files changed, 100 insertions(+), 7 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 605b1b06..ba74e1b0 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -28528,7 +28528,9 @@ paths: operationId: listBrands description: | Retrieves all brands for the workspace, including the default brand. - The default brand id always matches the workspace + The default brand id always matches the workspace id. + + Requires the `read_brands` OAuth scope. parameters: - name: Intercom-Version in: header @@ -28566,6 +28568,21 @@ paths: description: Unauthorized content: application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: $ref: "#/components/schemas/error" "/brands/{id}": @@ -28574,7 +28591,10 @@ paths: tags: - Brands operationId: retrieveBrand - description: Fetches a specific brand by its unique identifier + description: | + Fetches a specific brand by its unique identifier + + Requires the `read_brands` OAuth scope. parameters: - name: Intercom-Version in: header @@ -28608,6 +28628,21 @@ paths: description: Unauthorized content: application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: $ref: "#/components/schemas/error" '404': @@ -28622,7 +28657,7 @@ paths: type: error.list request_id: "req_12345" errors: - - code: not_found + - code: brand_not_found message: Brand not found "/emails": get: diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index c87a7a84..519b7af3 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -7472,7 +7472,10 @@ paths: tags: - IP Allowlist operationId: getIpAllowlist - description: Retrieve the current IP allowlist configuration for the workspace. + description: | + Retrieve the current IP allowlist configuration for the workspace. + + Requires the `manage_ip_allowlist` OAuth scope. responses: '200': description: Successful response @@ -7500,6 +7503,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" put: @@ -7515,6 +7525,12 @@ paths: description: | Update the IP allowlist configuration for the workspace. + Both `enabled` and `ip_allowlist` are optional. A field you omit is left unchanged, and a request with neither returns the current settings without changing anything. + + Every non-blank `ip_allowlist` entry must be an IPv4 address or an IPv4 range in CIDR notation. Blank entries are ignored and surrounding whitespace is trimmed. Any other entry, including an IPv6 address, returns a 422 `parameter_invalid` error. + + Requires the `manage_ip_allowlist` OAuth scope. + {% admonition type="warning" name="Lockout Protection" %} The API will reject updates that would lock out the caller's IP address. Ensure your current IP is included in the allowlist when enabling the feature. {% /admonition %} @@ -7545,6 +7561,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" '422': @@ -25665,7 +25688,9 @@ paths: operationId: listBrands description: | Retrieves all brands for the workspace, including the default brand. - The default brand id always matches the workspace + The default brand id always matches the workspace id. + + Requires the `read_brands` OAuth scope. parameters: - name: Intercom-Version in: header @@ -25703,6 +25728,21 @@ paths: description: Unauthorized content: application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: $ref: "#/components/schemas/error" "/brands/{id}": @@ -25711,7 +25751,10 @@ paths: tags: - Brands operationId: retrieveBrand - description: Fetches a specific brand by its unique identifier + description: | + Fetches a specific brand by its unique identifier + + Requires the `read_brands` OAuth scope. parameters: - name: Intercom-Version in: header @@ -25745,6 +25788,21 @@ paths: description: Unauthorized content: application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: $ref: "#/components/schemas/error" '404': @@ -25759,7 +25817,7 @@ paths: type: error.list request_id: "req_12345" errors: - - code: not_found + - code: brand_not_found message: Brand not found "/emails": get: From 7508092b432947c8c6e64024fc08db2044393320 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 22 Oct 2026 09:37:03 +0100 Subject: [PATCH 2/2] Apply the IP allowlist edits to Preview and note null fields Preview has the IP allowlist operations, so give them the same scope lines, missing-scope 401 examples, and optional-field and IPv4 text as 2.17. Also say that sending null for a field is the same as omitting it. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 25 ++++++++++++++++++++++++- descriptions/2.17/api.intercom.io.yaml | 2 +- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index ba74e1b0..7d8650fe 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -6170,7 +6170,10 @@ paths: tags: - IP Allowlist operationId: getIpAllowlist - description: Retrieve the current IP allowlist configuration for the workspace. + description: | + Retrieve the current IP allowlist configuration for the workspace. + + Requires the `manage_ip_allowlist` OAuth scope. responses: '200': description: Successful response @@ -6198,6 +6201,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" put: @@ -6213,6 +6223,12 @@ paths: description: | Update the IP allowlist configuration for the workspace. + Both `enabled` and `ip_allowlist` are optional. A field you omit is left unchanged, and a request with neither returns the current settings without changing anything. Sending `null` for a field is the same as omitting it. + + Every non-blank `ip_allowlist` entry must be an IPv4 address or an IPv4 range in CIDR notation. Blank entries are ignored and surrounding whitespace is trimmed. Any other entry, including an IPv6 address, returns a 422 `parameter_invalid` error. + + Requires the `manage_ip_allowlist` OAuth scope. + {% admonition type="warning" name="Lockout Protection" %} The API will reject updates that would lock out the caller's IP address. Ensure your current IP is included in the allowlist when enabling the feature. {% /admonition %} @@ -6243,6 +6259,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" '422': diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 519b7af3..933f959d 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -7525,7 +7525,7 @@ paths: description: | Update the IP allowlist configuration for the workspace. - Both `enabled` and `ip_allowlist` are optional. A field you omit is left unchanged, and a request with neither returns the current settings without changing anything. + Both `enabled` and `ip_allowlist` are optional. A field you omit is left unchanged, and a request with neither returns the current settings without changing anything. Sending `null` for a field is the same as omitting it. Every non-blank `ip_allowlist` entry must be an IPv4 address or an IPv4 range in CIDR notation. Blank entries are ignored and surrounding whitespace is trimmed. Any other entry, including an IPv6 address, returns a 422 `parameter_invalid` error.