Alias one ID into another

alias is a server-side operation that merges two identifiers into the same profile. The most common use is collapsing an external_id you wrote earlier into a different one (e.g. an internal user ID swap after a re-auth migration).

This endpoint requires a server key (gflux_secret_*). It accepts no publishable key, your browser cannot rewrite identities.

POST /v1/identify/alias HTTP/1.1
Host: api.getfluxly.com
Authorization: Bearer gflux_secret_abcdef1234
Content-Type: application/json
X-Idempotency-Key: 1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708

{
  "user_id": "user_42",
  "anonymous_id": "anon_a8f3c2"
}

Request body

At least one of anonymous_id or previous_id is required alongside user_id.

| Field | Type | Required | Notes | | --- | --- | --- | --- | | user_id | string | yes | The target identifier (the one that survives) | | anonymous_id | string | one of | Browser-side identifier to fold in | | previous_id | string | one of | A prior external_id to fold in | | request_id | string | no | Echoed back in the response, for log correlation |

Response, 200 OK

{
  "alias": {
    "user_id": "user_42",
    "anonymous_id": "anon_a8f3c2",
    "merged_at": "2026-05-16T07:00:00Z"
  }
}

Errors

| HTTP | error | When | | --- | --- | --- | | 400 | validation_error | Missing user_id or no source ID provided | | 403 | wrong_key_type | Tried to use a publishable key | | 409 | alias_conflict | Source ID already belongs to a different active profile |

alias_conflict is rare and almost always a code bug, your application is calling alias with the same source ID for two different targets. The response body names both profiles so you can pick one and re-alias.