From 70e700700e8f6e3072300ddbe96892376f480111 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 23 Sep 2026 16:26:54 +0100 Subject: [PATCH 1/2] Document OAuth client-credentials auth tokens in the Preview spec Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 103 +++++++++++++++++++++++++--- 1 file changed, 94 insertions(+), 9 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a5e8540b..fb720f62 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17822,7 +17822,7 @@ paths: - 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. + Stores a third-party credential in your workspace so a data connector can authenticate outbound requests with it. Set `token_type` to `text` (the default) to send the credential value as a request header yourself, or to `oauth` to have Intercom exchange OAuth client credentials for an access token and keep it refreshed. The value you supply is stored encrypted and is never returned by any endpoint, including this one. requestBody: content: application/json: @@ -17837,6 +17837,17 @@ paths: token_prefix: Bearer description: Used by the order status connector domain: api.fulfilment.example.com + OAuth credential: + value: + name: Fulfilment OAuth credential + token_type: oauth + oauth_configuration: + token_url: https://auth.fulfilment.example.com/oauth/token + client_id: fulfilment-connector + client_secret: 8f6e2b1a9c4d7e05 + scope: orders.read + description: Used by the order status connector + domain: api.fulfilment.example.com required: true responses: '201': @@ -17856,6 +17867,18 @@ paths: domain: api.fulfilment.example.com created_at: '2025-11-15T09:30:00Z' updated_at: '2025-11-15T09:30:00Z' + OAuth credential: + value: + type: auth_token + id: '12346' + name: Fulfilment OAuth credential + description: Used by the order status connector + token_type: oauth + 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' schema: "$ref": "#/components/schemas/auth_token" '400': @@ -17877,6 +17900,20 @@ paths: errors: - code: parameter_invalid message: domain must be a valid domain + Field not accepted for token_type: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_invalid + message: request_header_key is not accepted for oauth tokens + OAuth exchange failed: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_invalid + message: Could not obtain an access token from token_url with the given client credentials schema: "$ref": "#/components/schemas/error" '401': @@ -30232,23 +30269,30 @@ components: 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. + The fields accepted when storing a new third-party credential. Set `token_type` to `text` (the default) to store a plain credential value, or to `oauth` to have Intercom obtain and manage an access token via the OAuth client-credentials grant. properties: name: type: string description: A name for the credential, so a teammate can identify it later. example: Fulfilment API key + token_type: + type: string + description: The type of credential to store. Defaults to `text`. + enum: + - text + - oauth + example: text token_value: type: string - description: The credential value. Stored encrypted and never returned by any endpoint. + description: The credential value. Required when `token_type` is `text`. Must be omitted when `token_type` is `oauth`. 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. + description: The request header the credential is sent in. Required when `token_type` is `text`. Must be omitted when `token_type` is `oauth`, where it is fixed to `Authorization`. example: Authorization token_prefix: type: string - description: An optional prefix placed before the credential value in the header, for example `Bearer`. + description: An optional prefix placed before the credential value in the header, for example `Bearer`. Must be omitted when `token_type` is `oauth`, where it is fixed to `Bearer`. example: Bearer description: type: string @@ -30258,10 +30302,49 @@ components: type: string description: An optional domain to scope the credential to. example: api.fulfilment.example.com + oauth_configuration: + "$ref": "#/components/schemas/oauth_configuration" required: - name - - token_value - - request_header_key + oauth_configuration: + title: OAuth Configuration + type: object + x-tags: + - Auth Tokens + description: | + The OAuth client-credentials configuration Intercom uses to obtain and refresh an access token. Required when `token_type` is `oauth`. Must be omitted when `token_type` is `text`. + properties: + token_url: + type: string + description: The token endpoint Intercom exchanges the client credentials with. Must be an `https` URL. + example: https://auth.fulfilment.example.com/oauth/token + client_id: + type: string + description: The OAuth client ID. + example: fulfilment-connector + client_secret: + type: string + description: The OAuth client secret. Stored encrypted and never returned by any endpoint. + example: 8f6e2b1a9c4d7e05 + scope: + type: string + description: An optional scope to request from the token endpoint. + example: orders.read + audience: + type: string + description: An optional audience to request from the token endpoint. + example: https://api.fulfilment.example.com + request_format: + type: string + description: The format the client credentials are sent in when requesting a token. Defaults to `json`. + enum: + - json + - form_encoded + example: json + required: + - token_url + - client_id + - client_secret update_auth_token_request: title: Update Auth Token Request type: object @@ -44125,8 +44208,10 @@ tags: 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. + You can create a `text` credential to send yourself, or an `oauth` credential whose + access token Intercom obtains and refreshes automatically via the client-credentials + grant. Only credentials with a `token_type` of `text` can be updated. No endpoint ever + returns a credential value, client secret, refresh configuration, or OAuth configuration. - name: Banners description: | Retrieve the banners a contact matches and record dismissals, so you can display From eefe437fd79611984719a3ac61c4b533f5e31ff3 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 23 Sep 2026 16:57:08 +0100 Subject: [PATCH 2/2] Reject domain on OAuth credentials in the Preview auth tokens spec Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index fb720f62..e023c62c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17847,7 +17847,6 @@ paths: client_secret: 8f6e2b1a9c4d7e05 scope: orders.read description: Used by the order status connector - domain: api.fulfilment.example.com required: true responses: '201': @@ -17876,7 +17875,6 @@ paths: token_type: oauth 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' schema: @@ -30300,7 +30298,7 @@ components: example: Used by the order status connector domain: type: string - description: An optional domain to scope the credential to. + description: An optional domain to scope the credential to. Only applies when `token_type` is `text`; must be omitted for `oauth`. example: api.fulfilment.example.com oauth_configuration: "$ref": "#/components/schemas/oauth_configuration"