Skip to content

Document scopes and errors for Brands and IP allowlist operations #752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cathalging merged 2 commits into from
Oct 22, 2026
Merged

Document scopes and errors for Brands and IP allowlist operations #752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b8a64aa
Document scopes and errors for Brands and IP allowlist operations
cathalging Oct 21, 2026
7508092
Apply the IP allowlist edits to Preview and note null fields
cathalging Oct 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 62 additions & 4 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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 %}
Expand Down Expand Up @@ -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':
Expand Down Expand Up @@ -28528,7 +28551,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
Expand Down Expand Up @@ -28566,6 +28591,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}":
Expand All @@ -28574,7 +28614,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
Expand Down Expand Up @@ -28608,6 +28651,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':
Expand All @@ -28622,7 +28680,7 @@ paths:
type: error.list
request_id: "req_12345"
errors:
- code: not_found
- code: brand_not_found
message: Brand not found
"/emails":
get:
Expand Down
66 changes: 62 additions & 4 deletions descriptions/2.17/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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. 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 %}
Expand Down Expand Up @@ -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':
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}":
Expand All @@ -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
Expand Down Expand Up @@ -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':
Expand All @@ -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:
Expand Down
Loading