Create an identity verification secret

Request

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.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:Preview

Bodyapplication/json

namestringrequired

Human-readable name for the secret.

Example:"Production Web"

supports_androidboolean

Enable this secret for the Android SDK.

Example:false

supports_iosboolean

Enable this secret for the iOS SDK.

Example:false

supports_webboolean

Enable this secret for the Messenger on web.

Example:true

environment_idstring

Limit this secret to one environment, using the messenger_environment value from your Messenger installation code. Omit it for a secret that works in every environment.

Example:"k3x9q2m7pa"

curl -i -X POST \
  https://api.intercom.io/secure_mode_secrets \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "name": "Production Web",
    "supports_web": true
  }'

Responses

Secret created

Bodyapplication/json

typestring

value is "identity_verification_secret"

Example:"identity_verification_secret"

idstring

The id of the secret

Example:"102"

namestring

Human-readable name for the secret, used to identify it in rotation flows

Example:"Production Web"

supports_androidboolean

Whether the secret is enabled for the Android SDK

Example:false

supports_iosboolean

Whether the secret is enabled for the iOS SDK

Example:false

supports_webboolean

Whether the secret is enabled for the Messenger on web

Example:true

created_atinteger

The time the secret was created, as a Unix timestamp

Example:1734537243

environment_idstring or null

The messenger_environment value of the environment the secret is limited to, or null if the secret works in every environment

Example:"k3x9q2m7pa"

secretstring

The 256-bit HMAC signing key, base64url-encoded. Returned ONCE at creation time and never surfaced again.

Example:"9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A"

Response

{
  "type": "identity_verification_secret",
  "id": "103",
  "name": "Production Web",
  "secret": "9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A",
  "supports_android": false,
  "supports_ios": false,
  "supports_web": true,
  "created_at": 1734537500,
  "environment_id": null
}