Add Identity Verification Secret rotation API

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.</br>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