From 836211c23257571fdf00ded29915371333926d84 Mon Sep 17 00:00:00 2001 From: Thibault Candebat Date: Thu, 23 Apr 2026 14:39:45 +0100 Subject: [PATCH] Add Identity Verification Secret rotation API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the new public V3 endpoints for self-served rotation of Messenger Identity Verification secrets: - GET /secure_mode_secrets — list metadata (no signing material) - POST /secure_mode_secrets — create; secret returned ONCE - DELETE /secure_mode_secrets/{id} — soft-delete (rotation out) The create response includes the raw 256-bit HMAC secret; the list and delete responses do not. This write-once pattern mirrors AWS IAM access keys and GitHub fine-grained PATs. Companion to: - intercom/intercom#500245 - intercom/intercom#500247 - intercom/intercom#500250 --- descriptions/0/api.intercom.io.yaml | 269 ++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3f64864b..5ebd1b6b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14080,6 +14080,185 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/secure_mode_secrets": + get: + summary: List all identity verification secrets + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Identity Verification Secrets + operationId: listIdentityVerificationSecrets + description: | + Returns the identity verification secrets configured for your workspace. + + Each entry includes metadata only — the HMAC signing material itself is **never** returned by this endpoint. The raw secret is only available once, in the response to `POST /secure_mode_secrets`. Persist it at that moment. + responses: + '200': + description: Successful response + content: + application/json: + examples: + Successful response: + value: + type: list + data: + - type: identity_verification_secret + id: '102' + name: Production Web + supports_android: false + supports_ios: false + supports_web: true + created_at: 1734537243 + schema: + "$ref": "#/components/schemas/identity_verification_secret_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 6f8e61d8-6a9a-4f1e-bfbb-6c7c0c0aef1c + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + post: + summary: Create an identity verification secret + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Identity Verification Secrets + operationId: createIdentityVerificationSecret + description: | + Creates a new identity verification secret for your workspace. Intercom generates a 256-bit, cryptographically random value server-side and returns it once in the response. + + **This is the only opportunity to capture the secret.** Store it in your secure configuration immediately. The `secret` field is omitted from all subsequent responses (including `GET /secure_mode_secrets`) — if you lose it, you must rotate a new secret in and delete this one. + + You must enable the secret for at least one platform (`supports_android`, `supports_ios`, or `supports_web`). Rotation flow: create the new secret, roll it out to every client signing `user_hash` values, then delete the old secret with `DELETE /secure_mode_secrets/{id}` once traffic has cut over. + responses: + '201': + description: Secret created + content: + application/json: + examples: + Secret created: + value: + type: identity_verification_secret + id: '103' + name: Production Web + secret: 9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A + supports_android: false + supports_ios: false + supports_web: true + created_at: 1734537500 + schema: + "$ref": "#/components/schemas/identity_verification_secret_with_material" + '422': + description: Invalid parameters + content: + application/json: + examples: + Invalid parameters: + value: + type: error.list + request_id: 2fda7f9b-4a31-4c59-8b3f-3e5c4f8a1d22 + errors: + - code: parameter_invalid + message: name is required + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/create_identity_verification_secret_request" + examples: + web_only: + summary: Create a web-only secret + value: + name: Production Web + supports_web: true + multi_platform: + summary: Create a secret for web and mobile + value: + name: Production all-platform + supports_web: true + supports_ios: true + supports_android: true + "/secure_mode_secrets/{id}": + delete: + summary: Delete an identity verification secret + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + description: The unique identifier of the identity verification secret + example: '102' + required: true + schema: + type: string + tags: + - Identity Verification Secrets + operationId: deleteIdentityVerificationSecret + description: | + Soft-deletes an identity verification secret. After deletion, any `user_hash` values signed with that secret will no longer verify — Messenger sessions depending on it will be rejected on their next request. Use this to complete a rotation: create a new secret, roll it out, then delete the old one. + responses: + '204': + description: Secret deleted + '404': + description: Secret not found + content: + application/json: + examples: + Secret not found: + value: + type: error.list + request_id: 77b9d3c0-09e1-4d5f-8e6c-7d4a2f1b9a12 + errors: + - code: identity_verification_secret_not_found + message: Identity verification secret not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: c1c0477c-5b80-4874-be65-01ec8a9ffe14 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/segments": get: summary: List all segments @@ -25983,6 +26162,94 @@ components: nullable: true required: - id + identity_verification_secret: + title: Identity Verification Secret + type: object + x-tags: + - Identity Verification Secrets + description: Metadata for an HMAC secret used to sign `user_hash` values for Messenger identity verification. The `secret` field is intentionally omitted — it is only returned once, in the response to `POST /secure_mode_secrets`. + properties: + type: + type: string + description: value is "identity_verification_secret" + example: identity_verification_secret + id: + type: string + description: The id of the secret + example: '102' + name: + type: string + description: Human-readable name for the secret, used to identify it in rotation flows + example: Production Web + supports_android: + type: boolean + description: Whether the secret is enabled for the Android SDK + example: false + supports_ios: + type: boolean + description: Whether the secret is enabled for the iOS SDK + example: false + supports_web: + type: boolean + description: Whether the secret is enabled for the Messenger on web + example: true + created_at: + type: integer + description: The time the secret was created, as a Unix timestamp + example: 1734537243 + identity_verification_secret_with_material: + title: Identity Verification Secret (with material) + type: object + x-tags: + - Identity Verification Secrets + description: Returned once, at creation time, from `POST /secure_mode_secrets`. Includes the raw `secret` field. Persist the secret immediately — it is never retrievable again. + allOf: + - "$ref": "#/components/schemas/identity_verification_secret" + - type: object + properties: + secret: + type: string + description: The 256-bit HMAC signing key, base64url-encoded. Returned ONCE at creation time and never surfaced again. + example: 9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A + identity_verification_secret_list: + title: Identity Verification Secrets + type: object + description: A list of identity verification secrets for the workspace. The `secret` field is intentionally omitted from each entry. + properties: + type: + type: string + description: The type of the object + enum: + - list + example: list + data: + type: array + description: The identity verification secrets configured for the workspace. + items: + "$ref": "#/components/schemas/identity_verification_secret" + create_identity_verification_secret_request: + title: Create Identity Verification Secret Request + type: object + description: Request payload for creating a new identity verification secret. At least one platform flag must be `true`. + properties: + name: + type: string + description: Human-readable name for the secret. + example: Production Web + supports_android: + type: boolean + description: Enable this secret for the Android SDK. + example: false + supports_ios: + type: boolean + description: Enable this secret for the iOS SDK. + example: false + supports_web: + type: boolean + description: Enable this secret for the Messenger on web. + example: true + required: + - name intercom_version: description: Intercom API version.
By default, it's equal to the version set in the app package. @@ -29315,6 +29582,8 @@ tags: All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. - name: Help Center description: Everything about your Help Center +- name: Identity Verification Secrets + description: Manage HMAC signing secrets for Messenger identity verification — list, create, and rotate out. Signing material is returned only once, at creation time. - name: Internal Articles description: Everything about your Internal Articles - name: Jobs