Skip to content

Commit 836211c

Browse files
thibault-intercomthibault-intercom
committed
Add Identity Verification Secret rotation API
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
1 parent fffe17b commit 836211c

1 file changed

Lines changed: 269 additions & 0 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14080,6 +14080,185 @@ paths:
1408014080
message: Access Token Invalid
1408114081
schema:
1408214082
"$ref": "#/components/schemas/error"
14083+
"/secure_mode_secrets":
14084+
get:
14085+
summary: List all identity verification secrets
14086+
parameters:
14087+
- name: Intercom-Version
14088+
in: header
14089+
schema:
14090+
"$ref": "#/components/schemas/intercom_version"
14091+
tags:
14092+
- Identity Verification Secrets
14093+
operationId: listIdentityVerificationSecrets
14094+
description: |
14095+
Returns the identity verification secrets configured for your workspace.
14096+
14097+
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.
14098+
responses:
14099+
'200':
14100+
description: Successful response
14101+
content:
14102+
application/json:
14103+
examples:
14104+
Successful response:
14105+
value:
14106+
type: list
14107+
data:
14108+
- type: identity_verification_secret
14109+
id: '102'
14110+
name: Production Web
14111+
supports_android: false
14112+
supports_ios: false
14113+
supports_web: true
14114+
created_at: 1734537243
14115+
schema:
14116+
"$ref": "#/components/schemas/identity_verification_secret_list"
14117+
'401':
14118+
description: Unauthorized
14119+
content:
14120+
application/json:
14121+
examples:
14122+
Unauthorized:
14123+
value:
14124+
type: error.list
14125+
request_id: 6f8e61d8-6a9a-4f1e-bfbb-6c7c0c0aef1c
14126+
errors:
14127+
- code: unauthorized
14128+
message: Access Token Invalid
14129+
schema:
14130+
"$ref": "#/components/schemas/error"
14131+
post:
14132+
summary: Create an identity verification secret
14133+
parameters:
14134+
- name: Intercom-Version
14135+
in: header
14136+
schema:
14137+
"$ref": "#/components/schemas/intercom_version"
14138+
tags:
14139+
- Identity Verification Secrets
14140+
operationId: createIdentityVerificationSecret
14141+
description: |
14142+
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.
14143+
14144+
**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.
14145+
14146+
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.
14147+
responses:
14148+
'201':
14149+
description: Secret created
14150+
content:
14151+
application/json:
14152+
examples:
14153+
Secret created:
14154+
value:
14155+
type: identity_verification_secret
14156+
id: '103'
14157+
name: Production Web
14158+
secret: 9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A
14159+
supports_android: false
14160+
supports_ios: false
14161+
supports_web: true
14162+
created_at: 1734537500
14163+
schema:
14164+
"$ref": "#/components/schemas/identity_verification_secret_with_material"
14165+
'422':
14166+
description: Invalid parameters
14167+
content:
14168+
application/json:
14169+
examples:
14170+
Invalid parameters:
14171+
value:
14172+
type: error.list
14173+
request_id: 2fda7f9b-4a31-4c59-8b3f-3e5c4f8a1d22
14174+
errors:
14175+
- code: parameter_invalid
14176+
message: name is required
14177+
schema:
14178+
"$ref": "#/components/schemas/error"
14179+
'401':
14180+
description: Unauthorized
14181+
content:
14182+
application/json:
14183+
examples:
14184+
Unauthorized:
14185+
value:
14186+
type: error.list
14187+
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
14188+
errors:
14189+
- code: unauthorized
14190+
message: Access Token Invalid
14191+
schema:
14192+
"$ref": "#/components/schemas/error"
14193+
requestBody:
14194+
content:
14195+
application/json:
14196+
schema:
14197+
"$ref": "#/components/schemas/create_identity_verification_secret_request"
14198+
examples:
14199+
web_only:
14200+
summary: Create a web-only secret
14201+
value:
14202+
name: Production Web
14203+
supports_web: true
14204+
multi_platform:
14205+
summary: Create a secret for web and mobile
14206+
value:
14207+
name: Production all-platform
14208+
supports_web: true
14209+
supports_ios: true
14210+
supports_android: true
14211+
"/secure_mode_secrets/{id}":
14212+
delete:
14213+
summary: Delete an identity verification secret
14214+
parameters:
14215+
- name: Intercom-Version
14216+
in: header
14217+
schema:
14218+
"$ref": "#/components/schemas/intercom_version"
14219+
- name: id
14220+
in: path
14221+
description: The unique identifier of the identity verification secret
14222+
example: '102'
14223+
required: true
14224+
schema:
14225+
type: string
14226+
tags:
14227+
- Identity Verification Secrets
14228+
operationId: deleteIdentityVerificationSecret
14229+
description: |
14230+
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.
14231+
responses:
14232+
'204':
14233+
description: Secret deleted
14234+
'404':
14235+
description: Secret not found
14236+
content:
14237+
application/json:
14238+
examples:
14239+
Secret not found:
14240+
value:
14241+
type: error.list
14242+
request_id: 77b9d3c0-09e1-4d5f-8e6c-7d4a2f1b9a12
14243+
errors:
14244+
- code: identity_verification_secret_not_found
14245+
message: Identity verification secret not found
14246+
schema:
14247+
"$ref": "#/components/schemas/error"
14248+
'401':
14249+
description: Unauthorized
14250+
content:
14251+
application/json:
14252+
examples:
14253+
Unauthorized:
14254+
value:
14255+
type: error.list
14256+
request_id: c1c0477c-5b80-4874-be65-01ec8a9ffe14
14257+
errors:
14258+
- code: unauthorized
14259+
message: Access Token Invalid
14260+
schema:
14261+
"$ref": "#/components/schemas/error"
1408314262
"/segments":
1408414263
get:
1408514264
summary: List all segments
@@ -25983,6 +26162,94 @@ components:
2598326162
nullable: true
2598426163
required:
2598526164
- id
26165+
identity_verification_secret:
26166+
title: Identity Verification Secret
26167+
type: object
26168+
x-tags:
26169+
- Identity Verification Secrets
26170+
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`.
26171+
properties:
26172+
type:
26173+
type: string
26174+
description: value is "identity_verification_secret"
26175+
example: identity_verification_secret
26176+
id:
26177+
type: string
26178+
description: The id of the secret
26179+
example: '102'
26180+
name:
26181+
type: string
26182+
description: Human-readable name for the secret, used to identify it in rotation flows
26183+
example: Production Web
26184+
supports_android:
26185+
type: boolean
26186+
description: Whether the secret is enabled for the Android SDK
26187+
example: false
26188+
supports_ios:
26189+
type: boolean
26190+
description: Whether the secret is enabled for the iOS SDK
26191+
example: false
26192+
supports_web:
26193+
type: boolean
26194+
description: Whether the secret is enabled for the Messenger on web
26195+
example: true
26196+
created_at:
26197+
type: integer
26198+
description: The time the secret was created, as a Unix timestamp
26199+
example: 1734537243
26200+
identity_verification_secret_with_material:
26201+
title: Identity Verification Secret (with material)
26202+
type: object
26203+
x-tags:
26204+
- Identity Verification Secrets
26205+
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.
26206+
allOf:
26207+
- "$ref": "#/components/schemas/identity_verification_secret"
26208+
- type: object
26209+
properties:
26210+
secret:
26211+
type: string
26212+
description: The 256-bit HMAC signing key, base64url-encoded. Returned ONCE at creation time and never surfaced again.
26213+
example: 9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A
26214+
identity_verification_secret_list:
26215+
title: Identity Verification Secrets
26216+
type: object
26217+
description: A list of identity verification secrets for the workspace. The `secret` field is intentionally omitted from each entry.
26218+
properties:
26219+
type:
26220+
type: string
26221+
description: The type of the object
26222+
enum:
26223+
- list
26224+
example: list
26225+
data:
26226+
type: array
26227+
description: The identity verification secrets configured for the workspace.
26228+
items:
26229+
"$ref": "#/components/schemas/identity_verification_secret"
26230+
create_identity_verification_secret_request:
26231+
title: Create Identity Verification Secret Request
26232+
type: object
26233+
description: Request payload for creating a new identity verification secret. At least one platform flag must be `true`.
26234+
properties:
26235+
name:
26236+
type: string
26237+
description: Human-readable name for the secret.
26238+
example: Production Web
26239+
supports_android:
26240+
type: boolean
26241+
description: Enable this secret for the Android SDK.
26242+
example: false
26243+
supports_ios:
26244+
type: boolean
26245+
description: Enable this secret for the iOS SDK.
26246+
example: false
26247+
supports_web:
26248+
type: boolean
26249+
description: Enable this secret for the Messenger on web.
26250+
example: true
26251+
required:
26252+
- name
2598626253
intercom_version:
2598726254
description: Intercom API version.</br>By default, it's equal to the version
2598826255
set in the app package.
@@ -29315,6 +29582,8 @@ tags:
2931529582
All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation.
2931629583
- name: Help Center
2931729584
description: Everything about your Help Center
29585+
- name: Identity Verification Secrets
29586+
description: Manage HMAC signing secrets for Messenger identity verification — list, create, and rotate out. Signing material is returned only once, at creation time.
2931829587
- name: Internal Articles
2931929588
description: Everything about your Internal Articles
2932029589
- name: Jobs

0 commit comments

Comments
 (0)