# Link an existing user to your identity

Links a user that already exists on another identity to your identity.
Since the user's credentials are already set up, no invitation or password setup is required - once linked, the user gains access to the identity immediately and can select it on login.
In order to link a user you would need a stepped-up token. Before calling this operation you need to step-up ( issue a challenge `multi/stepup/challenges/otp/{channel}` )
More details on how to step-up a token can be found here [Step-Up](#tag/Step-up-Challenges/operation/stepupSCAChallenge)

Endpoint: POST /users/{user_id}/link
Version: v3
Security: auth_token, api-key

## Path parameters:

  - `user_id` (string, required)
    The unique identifier for the user.

## Header parameters:

  - `idempotency-ref` (string)
    A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

## Response 400 fields (application/json):

  - `message` (string)
    When present helps to identify and fix the problem.

  - `syntaxErrors` (object)
    Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.

  - `syntaxErrors.invalidFields` (array)

  - `syntaxErrors.invalidFields.params` (array)

  - `syntaxErrors.invalidFields.fieldName` (string)

  - `syntaxErrors.invalidFields.error` (string)
    Enum: "REQUIRED", "HAS_TEXT", "REQUIRES", "SIZE", "RANGE", "IN", "NOT_IN", "REGEX", "EXACTLY", "AT_LEAST", "AT_MOST", "ALL_OR_NONE"

## Response 403 fields (application/json):

  - `errorCode` (string)
    Enum: "INSUFFICIENT_PERMISSIONS"

## Response 404 fields (application/json):

  - `code` (string)

  - `message` (string)

## Response 409 fields (application/json):

  - `errorCode` (string)
    Enum: "USER_ALREADY_LINKED_TO_IDENTITY", "CREDENTIAL_NOT_FOUND", "KYB_MISSING", "PROFILE_MISMATCH", "EMAIL_DOMAIN_NOT_ALLOWED"

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)