Skip to content

Commit b39359c

Browse files
cathalgingclaude
cathalging
and
claude
authored
Document scopes and errors for Brands and IP allowlist operations (#752)
* 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> * 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) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent ce7300d commit b39359c

2 files changed

Lines changed: 124 additions & 8 deletions

File tree

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

Lines changed: 62 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6170,7 +6170,10 @@ paths:
61706170
tags:
61716171
- IP Allowlist
61726172
operationId: getIpAllowlist
6173-
description: Retrieve the current IP allowlist configuration for the workspace.
6173+
description: |
6174+
Retrieve the current IP allowlist configuration for the workspace.
6175+
6176+
Requires the `manage_ip_allowlist` OAuth scope.
61746177
responses:
61756178
'200':
61766179
description: Successful response
@@ -6198,6 +6201,13 @@ paths:
61986201
errors:
61996202
- code: unauthorized
62006203
message: Access Token Invalid
6204+
Token lacks required scope:
6205+
value:
6206+
type: error.list
6207+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
6208+
errors:
6209+
- code: token_unauthorized
6210+
message: Not authorized to access resource
62016211
schema:
62026212
"$ref": "#/components/schemas/error"
62036213
put:
@@ -6213,6 +6223,12 @@ paths:
62136223
description: |
62146224
Update the IP allowlist configuration for the workspace.
62156225

6226+
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.
6227+
6228+
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.
6229+
6230+
Requires the `manage_ip_allowlist` OAuth scope.
6231+
62166232
{% admonition type="warning" name="Lockout Protection" %}
62176233
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.
62186234
{% /admonition %}
@@ -6243,6 +6259,13 @@ paths:
62436259
errors:
62446260
- code: unauthorized
62456261
message: Access Token Invalid
6262+
Token lacks required scope:
6263+
value:
6264+
type: error.list
6265+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
6266+
errors:
6267+
- code: token_unauthorized
6268+
message: Not authorized to access resource
62466269
schema:
62476270
"$ref": "#/components/schemas/error"
62486271
'422':
@@ -28528,7 +28551,9 @@ paths:
2852828551
operationId: listBrands
2852928552
description: |
2853028553
Retrieves all brands for the workspace, including the default brand.
28531-
The default brand id always matches the workspace
28554+
The default brand id always matches the workspace id.
28555+
28556+
Requires the `read_brands` OAuth scope.
2853228557
parameters:
2853328558
- name: Intercom-Version
2853428559
in: header
@@ -28566,6 +28591,21 @@ paths:
2856628591
description: Unauthorized
2856728592
content:
2856828593
application/json:
28594+
examples:
28595+
Unauthorized:
28596+
value:
28597+
type: error.list
28598+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
28599+
errors:
28600+
- code: unauthorized
28601+
message: Access Token Invalid
28602+
Token lacks required scope:
28603+
value:
28604+
type: error.list
28605+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
28606+
errors:
28607+
- code: token_unauthorized
28608+
message: Not authorized to access resource
2856928609
schema:
2857028610
$ref: "#/components/schemas/error"
2857128611
"/brands/{id}":
@@ -28574,7 +28614,10 @@ paths:
2857428614
tags:
2857528615
- Brands
2857628616
operationId: retrieveBrand
28577-
description: Fetches a specific brand by its unique identifier
28617+
description: |
28618+
Fetches a specific brand by its unique identifier
28619+
28620+
Requires the `read_brands` OAuth scope.
2857828621
parameters:
2857928622
- name: Intercom-Version
2858028623
in: header
@@ -28608,6 +28651,21 @@ paths:
2860828651
description: Unauthorized
2860928652
content:
2861028653
application/json:
28654+
examples:
28655+
Unauthorized:
28656+
value:
28657+
type: error.list
28658+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
28659+
errors:
28660+
- code: unauthorized
28661+
message: Access Token Invalid
28662+
Token lacks required scope:
28663+
value:
28664+
type: error.list
28665+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
28666+
errors:
28667+
- code: token_unauthorized
28668+
message: Not authorized to access resource
2861128669
schema:
2861228670
$ref: "#/components/schemas/error"
2861328671
'404':
@@ -28622,7 +28680,7 @@ paths:
2862228680
type: error.list
2862328681
request_id: "req_12345"
2862428682
errors:
28625-
- code: not_found
28683+
- code: brand_not_found
2862628684
message: Brand not found
2862728685
"/emails":
2862828686
get:

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

Lines changed: 62 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7438,7 +7438,10 @@ paths:
74387438
tags:
74397439
- IP Allowlist
74407440
operationId: getIpAllowlist
7441-
description: Retrieve the current IP allowlist configuration for the workspace.
7441+
description: |
7442+
Retrieve the current IP allowlist configuration for the workspace.
7443+
7444+
Requires the `manage_ip_allowlist` OAuth scope.
74427445
responses:
74437446
'200':
74447447
description: Successful response
@@ -7466,6 +7469,13 @@ paths:
74667469
errors:
74677470
- code: unauthorized
74687471
message: Access Token Invalid
7472+
Token lacks required scope:
7473+
value:
7474+
type: error.list
7475+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
7476+
errors:
7477+
- code: token_unauthorized
7478+
message: Not authorized to access resource
74697479
schema:
74707480
"$ref": "#/components/schemas/error"
74717481
put:
@@ -7481,6 +7491,12 @@ paths:
74817491
description: |
74827492
Update the IP allowlist configuration for the workspace.
74837493

7494+
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.
7495+
7496+
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.
7497+
7498+
Requires the `manage_ip_allowlist` OAuth scope.
7499+
74847500
{% admonition type="warning" name="Lockout Protection" %}
74857501
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.
74867502
{% /admonition %}
@@ -7511,6 +7527,13 @@ paths:
75117527
errors:
75127528
- code: unauthorized
75137529
message: Access Token Invalid
7530+
Token lacks required scope:
7531+
value:
7532+
type: error.list
7533+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
7534+
errors:
7535+
- code: token_unauthorized
7536+
message: Not authorized to access resource
75147537
schema:
75157538
"$ref": "#/components/schemas/error"
75167539
'422':
@@ -25631,7 +25654,9 @@ paths:
2563125654
operationId: listBrands
2563225655
description: |
2563325656
Retrieves all brands for the workspace, including the default brand.
25634-
The default brand id always matches the workspace
25657+
The default brand id always matches the workspace id.
25658+
25659+
Requires the `read_brands` OAuth scope.
2563525660
parameters:
2563625661
- name: Intercom-Version
2563725662
in: header
@@ -25669,6 +25694,21 @@ paths:
2566925694
description: Unauthorized
2567025695
content:
2567125696
application/json:
25697+
examples:
25698+
Unauthorized:
25699+
value:
25700+
type: error.list
25701+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
25702+
errors:
25703+
- code: unauthorized
25704+
message: Access Token Invalid
25705+
Token lacks required scope:
25706+
value:
25707+
type: error.list
25708+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
25709+
errors:
25710+
- code: token_unauthorized
25711+
message: Not authorized to access resource
2567225712
schema:
2567325713
$ref: "#/components/schemas/error"
2567425714
"/brands/{id}":
@@ -25677,7 +25717,10 @@ paths:
2567725717
tags:
2567825718
- Brands
2567925719
operationId: retrieveBrand
25680-
description: Fetches a specific brand by its unique identifier
25720+
description: |
25721+
Fetches a specific brand by its unique identifier
25722+
25723+
Requires the `read_brands` OAuth scope.
2568125724
parameters:
2568225725
- name: Intercom-Version
2568325726
in: header
@@ -25711,6 +25754,21 @@ paths:
2571125754
description: Unauthorized
2571225755
content:
2571325756
application/json:
25757+
examples:
25758+
Unauthorized:
25759+
value:
25760+
type: error.list
25761+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
25762+
errors:
25763+
- code: unauthorized
25764+
message: Access Token Invalid
25765+
Token lacks required scope:
25766+
value:
25767+
type: error.list
25768+
request_id: a3e5b8e2-1234-5678-9abc-def012345678
25769+
errors:
25770+
- code: token_unauthorized
25771+
message: Not authorized to access resource
2571425772
schema:
2571525773
$ref: "#/components/schemas/error"
2571625774
'404':
@@ -25725,7 +25783,7 @@ paths:
2572525783
type: error.list
2572625784
request_id: "req_12345"
2572725785
errors:
25728-
- code: not_found
25786+
- code: brand_not_found
2572925787
message: Brand not found
2573025788
"/emails":
2573125789
get:

0 commit comments

Comments
 (0)