> ## Documentation Index
> Fetch the complete documentation index at: https://seam-feat-mintlify-migration-iteration.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Mobile App User Accounts with User Identities

> Learn how to use Seam user identities to manage mobile app user accounts.

## What is a User Identity?

Seam user identities are a feature for tracking and managing user accounts in your application. This feature assigns unique identifiers to each of your users, enabling you to issue and manage their [mobile credentials](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system) and access permissions. Each user identity is mapped to a user account in your app.

<figure>
  <img src="https://mintcdn.com/seam-feat-mintlify-migration-iteration/wHCCP74KFjF4xSb1/images/identities-accounts.png?fit=max&auto=format&n=wHCCP74KFjF4xSb1&q=85&s=22dfbb689e5b236ffc3813a65a9f7ec9" alt="Each user identity is mapped to a user account in your app." width="563" data-path="images/identities-accounts.png" />

  <figcaption />
</figure>

### User Identities Can Be Connected to Users in Multiple Access Control Systems

User identities can be linked to one [ACS user](/low-level-apis/access-systems/user-management) in each access control system. Any mobile credentials issued to these ACS users are consolidated under the user identity. Consequently, a user's mobile app account has access to these credentials through the user identity.

<figure>
  <img src="https://mintcdn.com/seam-feat-mintlify-migration-iteration/ttptfiJo49nVq_Qy/images/acs-identites.png?fit=max&auto=format&n=ttptfiJo49nVq_Qy&q=85&s=14d2daf833b810765abdf1a571bd91d3" alt="A user identity can be connected to an ACS user in each ACS." width="563" data-path="images/acs-identites.png" />

  <figcaption />
</figure>

***

## Create a User Identity and Associate it with an ACS User

### 1. Create a User Identity

To [create a user identity](/api/user_identities/create), you can specify any of the following characteristics:

* Unique user identity key (`user_identity_key`)
* Unique email address (`email_address`)
* Unique phone number (`phone_number`)
* Full name (`full_name`)

Note that if you specify one or more of the `user_identity_key`, `email_address`, or `phone_number`, each of these values must be unique within your [workspace](/core-concepts/workspaces/index).

<Tabs>
  <Tab title="JavaScript">
    **Command:**

    ```javascript theme={null}
    await seam.userIdentities.create({
      user_identity_key: 'jean_doe',
      email_address: 'jean@example.com',
      phone_number: '+15555550110',
      full_name: 'Jean Doe',
    })
    ```

    **Output:**

    ```json theme={null}
    {
      "user_identity_id": "22222222-2222-2222-2222-222222222222",
      "user_identity_key": "jean_doe",
      "email_address": "jean@example.com",
      "phone_number": "+15555550110",
      "display_name": "Jean Doe",
      "full_name": "Jean Doe",
      ...
    }
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/user_identities/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "user_identity_key": "jean_doe",
      "email_address": "jean@example.com",
      "phone_number": "+15555550110",
      "full_name": "Jean Doe"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "user_identity": {
        "user_identity_id": "22222222-2222-2222-2222-222222222222",
        "user_identity_key": "jean_doe",
        "email_address": "jean@example.com",
        "phone_number": "+15555550110",
        "display_name": "Jean Doe",
        "full_name": "Jean Doe",
        ...
      },
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Command:**

    ```python theme={null}
    seam.user_identities.create(
      user_identity_key = "jean_doe",
      email_address = "jean@example.com",
      phone_number = "+15555550110",
      full_name = "Jean Doe"
    )
    ```

    **Output:**

    ```
    UserIdentity(
      user_identity_id='22222222-2222-2222-2222-222222222222',
      user_identity_key='jean_doe',
      email_address='jean@example.com',
      phone_number='+15555550110',
      display_name='Jean Doe',
      full_name='Jean Doe',
      ...
    )
    ```
  </Tab>

  <Tab title="Ruby">
    **Command:**

    ```ruby theme={null}
    seam.user_identities.create(
      user_identity_key: "jean_doe",
      email_address: "jean@example.com",
      phone_number: "+15555550110",
      full_name: "Jean Doe",
    )
    ```

    **Output:**

    ```
    <Seam::Resources::UserIdentity:0x005f0
      user_identity_id="22222222-2222-2222-2222-222222222222"
      user_identity_key="jean_doe"
      email_address="jean@example.com"
      phone_number="+15555550110"
      display_name="Jean Doe"
      full_name="Jean Doe"
      ...
    >
    ```
  </Tab>

  <Tab title="PHP">
    **Command:**

    ```php theme={null}
    $seam->user_identities->create(
      user_identity_key: "jean_doe",
      email_address: "jean@example.com",
      phone_number: "+15555550110",
      full_name: "Jean Doe"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "user_identity_id": "22222222-2222-2222-2222-222222222222",
      "user_identity_key": "jean_doe",
      "email_address": "jean@example.com",
      "phone_number": "+15555550110",
      "display_name": "Jean Doe",
      "full_name": "Jean Doe",
      ...
    }
    ```
  </Tab>

  <Tab title="C#">
    **Command:**

    ```csharp theme={null}
    Coming soon!
    ```

    **Output:**

    ```json theme={null}
    Coming soon!
    ```
  </Tab>
</Tabs>

### 2. Assign an ACS User to the User Identity

To [link an ACS user with a user identity](/api/user_identities/add_acs_user), provide the ID of the user identity and the ID of the ACS user.

<Tabs>
  <Tab title="JavaScript">
    **Command:**

    ```javascript theme={null}
    const userIdentity = await seam.userIdentities.get({
      email_address: 'jean@example.com',
    })

    const acsUser = await seam.acs.users.get({
      email_address: 'jean@example.com',
    })

    await seam.userIdentities.addAcsUser({
      user_identity_id: userIdentity.user_identity_id,
      acs_user_id: acsUser.acs_user_id,
    })
    ```

    **Output:**

    ```
    // void
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/user_identities/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"email_address\": \"jane@example.com\"
    }")

    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/acs/users/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"email_address\": \"jane@example.com\"
    }")


    curl -X 'POST' \
      'https://connect.getseam.com/user_identities/add_acs_user' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer ${API_KEY}' \
      -H 'Content-Type: application/json' \
      -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${user_identity})\",
      \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
    }"
    ```

    **Response:**

    ```json theme={null}
    {
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Command:**

    ```python theme={null}
    user_identity = seam.user_identities.get(
      email_address = "jean@example.com"
    )

    acs_user = seam.acs.users.get(
      email_address = "jean@example.com"
    )

    seam.user_identities.add_acs_user(
      user_identity_id = user_identity.user_identity_id,
      acs_user_id = acs_user.acs_user_id
    )
    ```

    **Output:**

    ```
    None
    ```
  </Tab>

  <Tab title="Ruby">
    **Command:**

    ```ruby theme={null}
    user_identity = seam.user_identities.get(
      email_address: "jane@example.com"
    )

    acs_user = seam.acs.users.get(
      email_address: "jane@example.com"
    )

    seam.user_identities.add_acs_user(
      user_identity_id: user_identity.user_identity_id,
      acs_user_id: acs_user.acs_user_id,
    )
    ```

    **Output:**

    ```
    nil
    ```
  </Tab>

  <Tab title="PHP">
    **Command:**

    ```php theme={null}
    $user_identity = $seam->user_identities->get(
      email_address: "jean@example.com",
    );

    $acs_user = $seam->acs->users->get(
      email_address: "jean@example.com",
    );

    $seam->user_identities->add_acs_user(
        user_identity_id: $user_identity->user_identity_id,
        acs_user_id: $acs_user->acs_user_id
    );
    ```

    **Output:**

    ```
    null
    ```
  </Tab>

  <Tab title="C#">
    **Command:**

    ```csharp theme={null}
    Coming soon!
    ```

    **Output:**

    ```json theme={null}
    Coming soon!
    ```
  </Tab>
</Tabs>

***

## Removing a User Identity

When you [delete a user identity](/api/user_identities/delete), Seam automatically cleans up all other associated resources.

<Tabs>
  <Tab title="JavaScript">
    **Command:**

    ```javascript theme={null}
    await seam.userIdentities.delete({
      user_identity_id: '22222222-2222-2222-2222-222222222222',
    })
    ```

    **Output:**

    ```
    // void
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/user_identities/delete' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "user_identity_id": "22222222-2222-2222-2222-222222222222"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Command:**

    ```python theme={null}
    seam.user_identities.delete(
        user_identity_id = "22222222-2222-2222-2222-222222222222"
    )
    ```

    **Output:**

    ```
    None
    ```
  </Tab>

  <Tab title="Ruby">
    **Command:**

    ```ruby theme={null}
    seam.user_identities.delete(
      user_identity_id: "22222222-2222-2222-2222-222222222222"
    )
    ```

    **Output:**

    ```
    nil
    ```
  </Tab>

  <Tab title="PHP">
    **Command:**

    ```php theme={null}
    $seam->user_identities->delete(
      user_identity_id: "22222222-2222-2222-2222-222222222222"
    );
    ```

    **Output:**

    ```
    null
    ```
  </Tab>

  <Tab title="C#">
    **Command:**

    ```csharp theme={null}
    Coming soon!
    ```

    **Output:**

    ```json theme={null}
    Coming soon!
    ```
  </Tab>
</Tabs>