Skip to content

Commit 164402b

Browse files
cathalgingclaude
cathalging
and
claude
committed
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) <noreply@anthropic.com>
1 parent e0546c4 commit 164402b

2 files changed

Lines changed: 100 additions & 7 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28525,7 +28525,9 @@ paths:
2852528525
operationId: listBrands
2852628526
description: |
2852728527
Retrieves all brands for the workspace, including the default brand.
28528-
The default brand id always matches the workspace
28528+
The default brand id always matches the workspace id.
28529+
28530+
Requires the `read_brands` OAuth scope.
2852928531
parameters:
2853028532
- name: Intercom-Version
2853128533
in: header
@@ -28563,6 +28565,21 @@ paths:
2856328565
description: Unauthorized
2856428566
content:
2856528567
application/json:
28568+
examples:
28569+
Unauthorized:
28570+
value:
28571+
type: error.list
28572+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
28573+
errors:
28574+
- code: unauthorized
28575+
message: Access Token Invalid
28576+
Token lacks required scope:
28577+
value:
28578+
type: error.list
28579+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
28580+
errors:
28581+
- code: token_unauthorized
28582+
message: Not authorized to access resource
2856628583
schema:
2856728584
$ref: "#/components/schemas/error"
2856828585
"/brands/{id}":
@@ -28571,7 +28588,10 @@ paths:
2857128588
tags:
2857228589
- Brands
2857328590
operationId: retrieveBrand
28574-
description: Fetches a specific brand by its unique identifier
28591+
description: |
28592+
Fetches a specific brand by its unique identifier
28593+
28594+
Requires the `read_brands` OAuth scope.
2857528595
parameters:
2857628596
- name: Intercom-Version
2857728597
in: header
@@ -28605,6 +28625,21 @@ paths:
2860528625
description: Unauthorized
2860628626
content:
2860728627
application/json:
28628+
examples:
28629+
Unauthorized:
28630+
value:
28631+
type: error.list
28632+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
28633+
errors:
28634+
- code: unauthorized
28635+
message: Access Token Invalid
28636+
Token lacks required scope:
28637+
value:
28638+
type: error.list
28639+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
28640+
errors:
28641+
- code: token_unauthorized
28642+
message: Not authorized to access resource
2860828643
schema:
2860928644
$ref: "#/components/schemas/error"
2861028645
'404':
@@ -28619,7 +28654,7 @@ paths:
2861928654
type: error.list
2862028655
request_id: "req_12345"
2862128656
errors:
28622-
- code: not_found
28657+
- code: brand_not_found
2862328658
message: Brand not found
2862428659
"/emails":
2862528660
get:

‎descriptions/2.17/api.intercom.io.yaml‎

Lines changed: 62 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7472,7 +7472,10 @@ paths:
74727472
tags:
74737473
- IP Allowlist
74747474
operationId: getIpAllowlist
7475-
description: Retrieve the current IP allowlist configuration for the workspace.
7475+
description: |
7476+
Retrieve the current IP allowlist configuration for the workspace.
7477+
7478+
Requires the `manage_ip_allowlist` OAuth scope.
74767479
responses:
74777480
'200':
74787481
description: Successful response
@@ -7500,6 +7503,13 @@ paths:
75007503
errors:
75017504
- code: unauthorized
75027505
message: Access Token Invalid
7506+
Token lacks required scope:
7507+
value:
7508+
type: error.list
7509+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
7510+
errors:
7511+
- code: token_unauthorized
7512+
message: Not authorized to access resource
75037513
schema:
75047514
"$ref": "#/components/schemas/error"
75057515
put:
@@ -7515,6 +7525,12 @@ paths:
75157525
description: |
75167526
Update the IP allowlist configuration for the workspace.
75177527

7528+
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.
7529+
7530+
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.
7531+
7532+
Requires the `manage_ip_allowlist` OAuth scope.
7533+
75187534
{% admonition type="warning" name="Lockout Protection" %}
75197535
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.
75207536
{% /admonition %}
@@ -7545,6 +7561,13 @@ paths:
75457561
errors:
75467562
- code: unauthorized
75477563
message: Access Token Invalid
7564+
Token lacks required scope:
7565+
value:
7566+
type: error.list
7567+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
7568+
errors:
7569+
- code: token_unauthorized
7570+
message: Not authorized to access resource
75487571
schema:
75497572
"$ref": "#/components/schemas/error"
75507573
'422':
@@ -25662,7 +25685,9 @@ paths:
2566225685
operationId: listBrands
2566325686
description: |
2566425687
Retrieves all brands for the workspace, including the default brand.
25665-
The default brand id always matches the workspace
25688+
The default brand id always matches the workspace id.
25689+
25690+
Requires the `read_brands` OAuth scope.
2566625691
parameters:
2566725692
- name: Intercom-Version
2566825693
in: header
@@ -25700,6 +25725,21 @@ paths:
2570025725
description: Unauthorized
2570125726
content:
2570225727
application/json:
25728+
examples:
25729+
Unauthorized:
25730+
value:
25731+
type: error.list
25732+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
25733+
errors:
25734+
- code: unauthorized
25735+
message: Access Token Invalid
25736+
Token lacks required scope:
25737+
value:
25738+
type: error.list
25739+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
25740+
errors:
25741+
- code: token_unauthorized
25742+
message: Not authorized to access resource
2570325743
schema:
2570425744
$ref: "#/components/schemas/error"
2570525745
"/brands/{id}":
@@ -25708,7 +25748,10 @@ paths:
2570825748
tags:
2570925749
- Brands
2571025750
operationId: retrieveBrand
25711-
description: Fetches a specific brand by its unique identifier
25751+
description: |
25752+
Fetches a specific brand by its unique identifier
25753+
25754+
Requires the `read_brands` OAuth scope.
2571225755
parameters:
2571325756
- name: Intercom-Version
2571425757
in: header
@@ -25742,6 +25785,21 @@ paths:
2574225785
description: Unauthorized
2574325786
content:
2574425787
application/json:
25788+
examples:
25789+
Unauthorized:
25790+
value:
25791+
type: error.list
25792+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
25793+
errors:
25794+
- code: unauthorized
25795+
message: Access Token Invalid
25796+
Token lacks required scope:
25797+
value:
25798+
type: error.list
25799+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
25800+
errors:
25801+
- code: token_unauthorized
25802+
message: Not authorized to access resource
2574525803
schema:
2574625804
$ref: "#/components/schemas/error"
2574725805
'404':
@@ -25756,7 +25814,7 @@ paths:
2575625814
type: error.list
2575725815
request_id: "req_12345"
2575825816
errors:
25759-
- code: not_found
25817+
- code: brand_not_found
2576025818
message: Brand not found
2576125819
"/emails":
2576225820
get:

0 commit comments

Comments
 (0)