Bind an installation

Identity binding has a mobile half and a trusted-server half. The application requests an opaque binding code; your backend commits the external identity.

1. Mobile app requests a code

final code = await Engage.installation.issueBindingCode();
await yourBackend.bindEngageInstallation(code);

The app sends only the code to your own authenticated endpoint. It does not send or choose the external user ID.

2. Your backend derives identity

Inside your endpoint, load the customer ID from the verified session or access token:

Reject anonymous requests and never accept an arbitrary external ID from the client payload.

3. Commit the transition

POST /v1/installation-binding-transitions
Authorization: Bearer engk_…
Idempotency-Key: login-session:SESSION_ID
Content-Type: application/json

{
  "bindingCode": "eng_bind_…",
  "target": {
    "externalId": "customer_123"
  }
}

Example:

curl --request POST \
  "$ENGAGE_BASE_URL/v1/installation-binding-transitions" \
  --header "Authorization: Bearer $ENGAGE_ACCESS_KEY" \
  --header "Idempotency-Key: login-session:$SESSION_ID" \
  --header "Content-Type: application/json" \
  --data "{\"bindingCode\":\"$BINDING_CODE\",\"target\":{\"externalId\":\"$CUSTOMER_ID\"}}"

Response

The first commit returns 201 Created; an idempotent replay may return 200 OK.

{
  "transitionId": "019c…",
  "installationId": "019c…",
  "generation": 2,
  "state": "BOUND",
  "committedAt": "2026-08-18T10:00:00Z"
}

The SDK observes the committed state on synchronization. Do not poll the transition endpoint from the mobile app.

Security properties

• The binding code is short-lived and opaque.
• Only a trusted server access key can commit it.
• The target external ID comes from backend authentication.
• The idempotency key protects retries.
• A generation boundary prevents old-account operations from leaking into a new identity state.

Logout and account switching

Treat logout/account switching as an identity transition in your backend design, not as attribute deletion. Avoid wiping the installation unless the user explicitly requests privacy erasure.