From 1ee6212351d3083883e00a3818d5bba260a9502a Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Mon, 14 Sep 2026 17:42:21 +0100 Subject: [PATCH 1/4] Document the Preview auth_tokens read endpoints Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 247 ++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 005fda72..abb44126 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17638,6 +17638,155 @@ paths: value: description: Trying to archieve archived: true + "/auth_tokens": + get: + summary: List all auth tokens + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: per_page + in: query + required: false + description: The number of results to return per page. Defaults to 20, minimum 1, maximum 50. + schema: + type: integer + default: 20 + minimum: 1 + maximum: 50 + - name: starting_after + in: query + required: false + description: The cursor value from `pages.next.starting_after` in a previous response. Used to paginate through results. + schema: + type: string + tags: + - Auth Tokens + operationId: listAuthTokens + description: | + Returns a paginated list of the workspace's stored third-party credentials. Use this to discover the id of a credential you want a data connector to authenticate with — that id is not otherwise available over REST. Only metadata is returned; credential values are never exposed. Credentials created by app packages or by Intercom's own integrations are not listed. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: list + data: + - type: auth_token + id: '12345' + name: Fulfilment API key + description: Used by the order status connector + token_type: header + request_header_key: Authorization + domain: api.fulfilment.example.com + created_at: '2025-11-15T09:30:00Z' + updated_at: '2026-01-20T14:22:15Z' + pages: + type: pages + per_page: 20 + next: + starting_after: WzE3MDc1OTQ3MTUuMCwxMjM0NV0= + schema: + "$ref": "#/components/schemas/auth_token_list" + '400': + description: Bad Request + content: + application/json: + examples: + Invalid cursor: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: client_error + message: Invalid starting_after param. Please try again using a starting_after value from a paginated response + 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" + "/auth_tokens/{id}": + get: + summary: Retrieve 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: integer + tags: + - Auth Tokens + operationId: retrieveAuthToken + description: | + Returns the metadata for a single stored third-party credential. A credential that the list endpoint does not return is also not retrievable here, and responds with 404. + responses: + '200': + 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: header + 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" + '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" + '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 @@ -29596,6 +29745,97 @@ components: type: array items: $ref: "#/components/schemas/team_metric" + auth_token: + title: Auth Token + type: object + x-tags: + - Auth Tokens + description: | + Metadata for a stored third-party credential that data connectors use to authenticate outbound requests. Only metadata is returned — the credential value itself, and its refresh and OAuth configuration, are never exposed. + properties: + type: + type: string + description: The type of object - `auth_token`. + enum: + - auth_token + example: auth_token + id: + type: string + description: The unique identifier for the auth token. + example: '12345' + name: + type: string + description: The name given to the credential when it was created. + example: Fulfilment API key + nullable: true + description: + type: string + description: An optional description of what the credential is used for. + example: Used by the order status connector + nullable: true + 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 + nullable: true + request_header_key: + type: string + description: The request header the credential is sent in. + example: Authorization + nullable: true + domain: + type: string + description: The domain the credential is scoped to, if one was set. + example: api.fulfilment.example.com + nullable: true + created_at: + type: string + description: The time the credential was created, as an ISO 8601 timestamp. + example: '2025-11-15T09:30:00Z' + nullable: true + updated_at: + type: string + description: The time the credential was last updated, as an ISO 8601 timestamp. + example: '2026-01-20T14:22:15Z' + nullable: true + auth_token_list: + title: Auth Token List + type: object + description: A paginated list of auth tokens. + properties: + type: + type: string + description: The type of object - `list`. + enum: + - list + example: list + data: + type: array + description: An array of auth token objects. + items: + "$ref": "#/components/schemas/auth_token" + pages: + type: object + description: Pagination information. + properties: + type: + type: string + example: pages + enum: + - pages + per_page: + type: integer + description: The number of results per page. + example: 20 + next: + type: object + nullable: true + description: Cursor for the next page of results. + properties: + starting_after: + type: string + description: The cursor value to use for the next page. + example: WzE3MDc1OTQ3MTUuMCwxMjM0NV0= away_status_reason: type: object properties: @@ -43205,6 +43445,13 @@ tags: description: Everything about your Away Status Reasons - name: Audiences 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. - name: Banners description: | Retrieve the banners a contact matches and record dismissals, so you can display From 1dbb161ee15efeaee257d2d4c976a63d5f17f882 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Mon, 14 Sep 2026 17:59:45 +0100 Subject: [PATCH 2/4] Type the auth token path parameter as a string Token ids are serialised as strings in the response, and the sibling connector endpoints already declare their path id as a string. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index abb44126..bf3f69ba 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17732,9 +17732,9 @@ paths: in: path required: true description: The unique identifier for the auth token. - example: 12345 + example: '12345' schema: - type: integer + type: string tags: - Auth Tokens operationId: retrieveAuthToken From 0ed325bb6961fee253abee62e7416eff1073a383 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 15 Sep 2026 09:41:09 +0100 Subject: [PATCH 3/4] Correct which credentials the auth_tokens endpoints list App package and integration credentials are included, not excluded. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index bf3f69ba..bd1e1972 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17665,7 +17665,7 @@ paths: - Auth Tokens operationId: listAuthTokens description: | - Returns a paginated list of the workspace's stored third-party credentials. Use this to discover the id of a credential you want a data connector to authenticate with — that id is not otherwise available over REST. Only metadata is returned; credential values are never exposed. Credentials created by app packages or by Intercom's own integrations are not listed. + Returns a paginated list of the workspace's stored third-party credentials, including those installed by apps and those created by integrations. Use this to discover the id of a credential you want a data connector to authenticate with — that id is not otherwise available over REST. Only metadata is returned; credential values are never exposed. Credentials minted for an individual teammate's MCP access are not listed. responses: '200': description: successful From 27d2758b5fbe945345fd05a9c1721c8b53685399 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 15 Sep 2026 14:46:31 +0100 Subject: [PATCH 4/4] Describe the auth_tokens list as non-exhaustive The previous wording said app package and integration credentials are included. The adapter reverted to with_app_package_tokens: false, so they are not. The wording before that was also wrong in the other direction: it said no integration credentials are listed, but the allowlist covers Calendly, HubSpot Meetings and Marketo. Describes what the filter actually does instead of enumerating a set that changes. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index bd1e1972..151bcfc5 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17665,7 +17665,7 @@ paths: - Auth Tokens operationId: listAuthTokens description: | - Returns a paginated list of the workspace's stored third-party credentials, including those installed by apps and those created by integrations. Use this to discover the id of a credential you want a data connector to authenticate with — that id is not otherwise available over REST. Only metadata is returned; credential values are never exposed. Credentials minted for an individual teammate's MCP access are not listed. + Returns a paginated list of the workspace's stored third-party credentials. Use this to discover the id of a credential you want a data connector to authenticate with — that id is not otherwise available over REST. Only metadata is returned; credential values are never exposed. The list is not exhaustive: credentials a teammate created are listed, as are those created by some Intercom integrations, but credentials installed by an app package, those created by most other integrations, and those minted for an individual teammate's MCP access are not. responses: '200': description: successful