POST /v1/identify/alias

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.