diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a5e8540b..7b8658ab 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: @@ -17836,7 +17836,16 @@ paths: request_header_key: Authorization 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 required: true responses: '201': @@ -17853,7 +17862,19 @@ paths: token_type: text request_header_key: Authorization token_prefix: Bearer - domain: api.fulfilment.example.com + domain: null + 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: null created_at: '2025-11-15T09:30:00Z' updated_at: '2025-11-15T09:30:00Z' schema: @@ -17870,13 +17891,20 @@ paths: errors: - code: parameter_not_found message: name parameter is required - Rejected field value: + 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: domain must be a valid domain + message: Could not obtain an access token from token_url with the given client credentials schema: "$ref": "#/components/schemas/error" '401': @@ -17907,6 +17935,20 @@ paths: message: Writing an auth token requires an access token associated with a teammate schema: "$ref": "#/components/schemas/error" + '429': + description: Too many OAuth credentials created for this workspace in the last minute + content: + application/json: + examples: + Rate limited: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: rate_limit_exceeded + message: Exceeded rate limit of 10 OAuth auth token creations per minute + schema: + "$ref": "#/components/schemas/error" "/auth_tokens/{id}": get: summary: Retrieve an auth token @@ -17993,7 +18035,7 @@ paths: - 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`. + 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. The `domain` is read-only, and `request_header_key` cannot be changed on a credential that has a domain. 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: @@ -30232,36 +30274,78 @@ 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 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 + 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 @@ -30286,10 +30370,6 @@ components: 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 @@ -44125,8 +44205,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