From 0a7760be6fedfedc3951fc27285a5474613fcb02 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Fri, 18 Sep 2026 11:29:27 +0100 Subject: [PATCH 1/3] Document the Preview auth token write endpoints Adds POST /auth_tokens and PATCH /auth_tokens/{id} to the Preview spec, alongside the read endpoints already documented there, with request schemas for each and the error responses they can return. Also corrects the token_type example on the auth_token schema: the API returns "text", not "header". Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 274 +++++++++++++++++++++++++++- 1 file changed, 268 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4f816c2b..54888b89 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17774,6 +17774,101 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + post: + summary: Create an auth token + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Auth Tokens + operationId: createAuthToken + description: | + Stores a third-party credential in your workspace so a data connector can authenticate outbound requests with it. Only credentials with a `token_type` of `text` can be created here — the credential value is sent as a request header. The value you supply is stored encrypted and is never returned by any endpoint, including this one. + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/create_auth_token_request" + examples: + successful: + value: + name: Fulfilment API key + token_value: sk_live_9f3c2a7b41e8 + request_header_key: Authorization + token_prefix: Bearer + description: Used by the order status connector + domain: api.fulfilment.example.com + required: true + responses: + '201': + description: successful + content: + application/json: + examples: + successful: + value: + type: auth_token + id: '12345' + name: Fulfilment API key + description: Used by the order status connector + token_type: text + request_header_key: Authorization + domain: api.fulfilment.example.com + created_at: '2025-11-15T09:30:00Z' + updated_at: '2025-11-15T09:30:00Z' + schema: + "$ref": "#/components/schemas/auth_token" + '400': + description: Bad Request + content: + application/json: + examples: + Missing required field: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_not_found + message: name parameter is required + Rejected field value: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_invalid + message: domain must be a valid domain + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + No teammate associated with the access token: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: forbidden + message: Writing an auth token requires an access token associated with a teammate + schema: + "$ref": "#/components/schemas/error" "/auth_tokens/{id}": get: summary: Retrieve an auth token @@ -17841,6 +17936,111 @@ paths: message: Resource Not Found schema: "$ref": "#/components/schemas/error" + patch: + summary: Update an auth token + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the auth token. + example: '12345' + schema: + type: string + tags: + - Auth Tokens + operationId: updateAuthToken + description: | + Updates the metadata of a stored third-party credential. A field you omit keeps its current value. The credential value itself cannot be changed here and is never returned. Only credentials with a `token_type` of `text` can be updated; any other type responds with `400`. A credential the list endpoint does not return is also not updatable, and responds with `404`. + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/update_auth_token_request" + examples: + successful: + value: + name: Fulfilment API key (rotated host) + description: Used by the order status connector + required: true + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: auth_token + id: '12345' + name: Fulfilment API key (rotated host) + description: Used by the order status connector + token_type: text + request_header_key: Authorization + domain: api.fulfilment.example.com + created_at: '2025-11-15T09:30:00Z' + updated_at: '2026-01-20T14:22:15Z' + schema: + "$ref": "#/components/schemas/auth_token" + '400': + description: Bad Request + content: + application/json: + examples: + Unsupported token type: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_invalid + message: Only auth tokens with token_type "text" can be updated through the API + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + No teammate associated with the access token: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: forbidden + message: Writing an auth token requires an access token associated with a teammate + schema: + "$ref": "#/components/schemas/error" + '404': + description: Not Found + content: + application/json: + examples: + Auth token not found: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" "/data_connectors": get: summary: List all data connectors @@ -29830,7 +30030,7 @@ components: token_type: type: string description: How the credential is presented to the external API, for example as a header value or an HMAC signature. - example: header + example: text nullable: true request_header_key: type: string @@ -29852,6 +30052,66 @@ components: description: The time the credential was last updated, as an ISO 8601 timestamp. example: '2026-01-20T14:22:15Z' nullable: true + create_auth_token_request: + title: Create Auth Token Request + type: object + x-tags: + - Auth Tokens + description: | + The fields accepted when storing a new third-party credential. The credential is created with a `token_type` of `text`; no other type can be created over the API. + properties: + name: + type: string + description: A name for the credential, so a teammate can identify it later. + example: Fulfilment API key + token_value: + type: string + description: The credential value. Stored encrypted and never returned by any endpoint. + example: sk_live_9f3c2a7b41e8 + request_header_key: + type: string + description: The request header the credential is sent in. + example: Authorization + token_prefix: + type: string + description: An optional prefix placed before the credential value in the header, for example `Bearer`. + example: Bearer + description: + type: string + description: An optional description of what the credential is used for. + example: Used by the order status connector + domain: + type: string + description: An optional domain to scope the credential to. + example: api.fulfilment.example.com + required: + - name + - token_value + - request_header_key + update_auth_token_request: + title: Update Auth Token Request + type: object + x-tags: + - Auth Tokens + description: | + The fields accepted when updating a stored third-party credential. Every field is optional, and one you omit keeps its current value. The credential value cannot be changed here. + properties: + name: + type: string + description: A name for the credential, so a teammate can identify it later. + example: Fulfilment API key + request_header_key: + type: string + description: The request header the credential is sent in. + example: Authorization + description: + type: string + description: An optional description of what the credential is used for. + example: Used by the order status connector + domain: + type: string + description: An optional domain to scope the credential to. + example: api.fulfilment.example.com auth_token_list: title: Auth Token List type: object @@ -43539,11 +43799,13 @@ tags: description: Everything about your Audiences - name: Auth Tokens description: | - Read the metadata of the third-party credentials stored in your workspace, so you can - find the id of the credential a data connector should authenticate with. These endpoints - are part of the `Preview` API version and require an OAuth token with the - `read_auth_tokens` scope. They are read-only and never return credential values, refresh - configuration, or OAuth configuration. + Read and write the third-party credentials stored in your workspace, so you can find the + id of the credential a data connector should authenticate with, and store a new one + without leaving your integration. These endpoints are part of the `Preview` API version. + Reading requires an OAuth token with the `read_auth_tokens` scope; creating and updating + require the `write_auth_tokens` scope and an access token associated with a teammate. + Only credentials with a `token_type` of `text` can be created or updated. No endpoint + ever returns a credential value, refresh configuration, or OAuth configuration. - name: Banners description: | Retrieve the banners a contact matches and record dismissals, so you can display From eac136cf5286209d7d0236ad78f23317daefacc4 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Fri, 18 Sep 2026 14:32:29 +0100 Subject: [PATCH 2/3] Document token_prefix on the auth token endpoints token_prefix is now returned by every auth token operation and accepted when updating one. Also corrects two response examples that showed a token_type of header, which is not a value these endpoints return. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 54888b89..3ffd71f4 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17734,8 +17734,9 @@ paths: id: '12345' name: Fulfilment API key description: Used by the order status connector - token_type: header + token_type: text request_header_key: Authorization + token_prefix: Bearer domain: api.fulfilment.example.com created_at: '2025-11-15T09:30:00Z' updated_at: '2026-01-20T14:22:15Z' @@ -17815,6 +17816,7 @@ paths: description: Used by the order status connector token_type: text request_header_key: Authorization + token_prefix: Bearer domain: api.fulfilment.example.com created_at: '2025-11-15T09:30:00Z' updated_at: '2025-11-15T09:30:00Z' @@ -17901,8 +17903,9 @@ paths: id: '12345' name: Fulfilment API key description: Used by the order status connector - token_type: header + token_type: text request_header_key: Authorization + token_prefix: Bearer domain: api.fulfilment.example.com created_at: '2025-11-15T09:30:00Z' updated_at: '2026-01-20T14:22:15Z' @@ -17980,6 +17983,7 @@ paths: description: Used by the order status connector token_type: text request_header_key: Authorization + token_prefix: Bearer domain: api.fulfilment.example.com created_at: '2025-11-15T09:30:00Z' updated_at: '2026-01-20T14:22:15Z' @@ -30037,6 +30041,11 @@ components: description: The request header the credential is sent in. example: Authorization nullable: true + token_prefix: + type: string + description: The prefix placed before the credential value in the header, for example `Bearer`. + example: Bearer + nullable: true domain: type: string description: The domain the credential is scoped to, if one was set. @@ -30104,6 +30113,10 @@ components: type: string description: The request header the credential is sent in. example: Authorization + token_prefix: + type: string + description: An optional prefix placed before the credential value in the header, for example `Bearer`. + example: Bearer description: type: string description: An optional description of what the credential is used for. From d82903b2d091a9c30165505aceacb643acc974ea Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Mon, 21 Sep 2026 11:27:34 +0100 Subject: [PATCH 3/3] Pin the auth token endpoints to the Preview version header The four operations referenced the unrestricted intercom_version schema, so generated clients offered released versions that do not expose them. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3ffd71f4..a442e38e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17699,7 +17699,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" - name: per_page in: query required: false @@ -17781,7 +17781,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" tags: - Auth Tokens operationId: createAuthToken @@ -17878,7 +17878,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" - name: id in: path required: true @@ -17945,7 +17945,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" - name: id in: path required: true