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 and access permissions. Each user identity is mapped to a user account in your app.

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

User identities can be linked to one ACS user 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.

---

Create a User Identity and Associate it with an ACS User

1. Create a User Identity

To create a user identity, 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.

Python

Command:

seam.user_identities.create(
  user_identity_key = "jean_doe",
  email_address = "[email protected]",
  phone_number = "[phone]",
  full_name = "Jean Doe"
)

Output:

UserIdentity(
  user_identity_id='22222222-2222-2222-2222-222222222222',
  user_identity_key='jean_doe',
  email_address='[email protected]',
  phone_number='[phone]',
  display_name='Jean Doe',
  full_name='Jean Doe',
  ...
)

cURL (bash)

Request:

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": "[email protected]",
  "phone_number": "[phone]",
  "full_name": "Jean Doe"
}'

Response:

{
  "user_identity": {
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "user_identity_key": "jean_doe",
    "email_address": "[email protected]",
    "phone_number": "[phone]",
    "display_name": "Jean Doe",
    "full_name": "Jean Doe",
    ...
  },
  "ok": true
}

JavaScript

Command:

await seam.userIdentities.create({
  user_identity_key: "jean_doe",
  email_address: "[email protected]",
  phone_number: "[phone]",
  full_name: "Jean Doe",
});

Output:

{
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  "user_identity_key": "jean_doe",
  "email_address": "[email protected]",
  "phone_number": "[phone]",
  "display_name": "Jean Doe",
  "full_name": "Jean Doe",
  ...
}

Ruby

Command:

seam.user_identities.create(
  user_identity_key: "jean_doe",
  email_address: "[email protected]",
  phone_number: "[phone]",
  full_name: "Jean Doe",
)

Output:

<Seam::Resources::UserIdentity:0x005f0
  user_identity_id="22222222-2222-2222-2222-222222222222"
  user_identity_key="jean_doe"
  email_address="[email protected]"
  phone_number="[phone]"
  display_name="Jean Doe"
  full_name="Jean Doe"
  ...
>

PHP

Command:

$seam->user_identities->create(
  user_identity_key: "jean_doe",
  email_address: "[email protected]",
  phone_number: "[phone]",
  full_name: "Jean Doe"
);

Output:

{
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  "user_identity_key": "jean_doe",
  "email_address": "[email protected]",
  "phone_number": "[phone]",
  "display_name": "Jean Doe",
  "full_name": "Jean Doe",
  ...
}

C#

Command:

Coming soon!

Output:

Coming soon!

2. Assign an ACS User to the User Identity

To link an ACS user with a user identity, provide the ID of the user identity and the ID of the ACS user.

Python

Command:

user_identity = seam.user_identities.get(
  email_address = "[email protected]"
)

acs_user = seam.acs.users.get(
  email_address = "[email protected]"
)

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

Output:

None

cURL (bash)

Request:

# 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\": \"[email protected]\"
}")

# 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\": \"[email protected]\"
}")


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:

{
  "ok": true
}

JavaScript

Command:

const userIdentity = await seam.userIdentities.get({
  email_address: "[email protected]",
});

const acsUser = await seam.acs.users.get({
  email_address: "[email protected]",
});

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

Output:

// void

Ruby

Command:

user_identity = seam.user_identities.get(
  email_address: "[email protected]"
)

acs_user = seam.acs.users.get(
  email_address: "[email protected]"
)

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

Output:

nil

PHP

Command:

$user_identity = $seam->user_identities->get(
  email_address: "[email protected]",
);

$acs_user = $seam->acs->users->get(
  email_address: "[email protected]",
);

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

Output:

null

C#

Command:

Coming soon!

Output:

Coming soon!

---

Removing a User Identity

To delete a user identity, you must first delete any ACS credentials and ACS users associated with the user identity. You must also deactivate any associated phones. Then, delete the user identity.

Python

Command:

import asyncio

user_identity_id = "22222222-2222-2222-2222-222222222222"

async def delete_user_identity(user_identity_id):
  # Step 1: List and delete all client sessions 
  # associated with the user identity.
  
  # List the client sessions.
  client_sessions = await seam.client_sessions.list(
    user_identity_id = user_identity_id
  )

  # Delete the client sessions.
  for session in client_sessions:
    await seam.client_sessions.delete(
      session_id=session['client_session_id']
    )

  # Step 2: List and delete all ACS users and credentials 
  # associated with the user identity.
  
  # List the ACS users.
  acs_users = await seam.acs.users.list(
    user_identity_id=user_identity_id
  )

  for acs_user in acs_users:
    # List the credentials for each ACS user.
    credentials = await seam.acs.credentials.list(
      acs_user_id=acs_user['acs_user_id']
    )

    # Delete the credentials.
    for credential in credentials:
      await seam.acs.credentials.delete(
        acs_credential_id=credential['acs_credential_id']
      )
    
      await asyncio.gather(*[
        wait_for_acs_credential_deleted(credential)
        for credential in credentials
      ])
    
    # Delete the ACS users.
    await seam.acs.users.delete(
      acs_user_id=acs_user['acs_user_id']
    )

    await asyncio.gather(*[
      wait_for_acs_user_deleted(acs_user) for acs_user in acs_users
    ])

  # Step 3: List and deactivate all phones 
  # associated with the user identity.
  
  # List the phones.
  phones = await seam.phones.list(
    owner_user_identity_id=user_identity_id
  )

  # Deactivate the phones.
  for phone in phones:
    await seam.phones.deactivate(
      device_id=phone['device_id']
    )

  await asyncio.gather(*[
    wait_for_phone_deactivated(phone) for phone in phones
  ])

  # Step 4: Delete the user identity.
  await seam.user_identities.delete(
    user_identity_id=user_identity_id
  )

# Helper functions for waiting on deletion events
async def wait_for_event(event_type, event_filter):
  while True:
    events = await seam.events.list(event_type=event_type)
    if any(event_filter(event) for event in events):
      break

async def wait_for_acs_user_deleted(acs_user):
  await wait_for_event(
    'acs_user.deleted',
    lambda event: 'acs_user_id' in event and
                  event.acs_user_id == acs_user.acs_user_id
  )

async def wait_for_acs_credential_deleted(acs_credential):
  await wait_for_event(
    'acs_credential.deleted',
    lambda event: 'acs_credential_id' in event and
                  event.acs_credential_id == acs_credential.acs_credential_id
  )

async def wait_for_phone_deactivated(phone):
  await wait_for_event(
    'phone.deactivated',
    lambda event: 'device_id' in event and
                  event.device_id == phone.device_id
  )

await delete_user_identity(user_identity_id)

Output:

None

JavaScript

Command:

const userIdentityId = "22222222-2222-2222-2222-222222222222";

// Step 1: List and delete all client sessions 
// associated with the user identity.

// List the client sessions.
const clientSessions = await seam.clientSessions.list({
  user_identity_id: userIdentityId,
});

// Delete each returned client session.
for (const clientSession of clientSessions) {
  await seam.clientSessions.delete({
    client_session_id: clientSession.client_session_id,
  });
}

// Step 2: List and delete all ACS users and credentials 
// associated with the user identity.

// List the ACS users.
const acsUsers = await seam.acs.users.list({
  user_identity_id: userIdentityId,
});

for (const acsUser of acsUsers) {
  // For each returned ACS user, list the associated credentials.
  const credentials = await seam.acs.credentials.list({
    acs_user_id: acsUser.acs_user_id,
  });
  
  // Delete each returned credential.
  for (const credential of credentials) {
    await seam.acs.credentials.delete({
      acs_credential_id: credential.acs_credential_id,
    });
  
    // Wait until each credential has been deleted.
    // You can watch for acs_credential.deleted events.
  
  }
    
  // Delete each ACS user returned previously.
  await seam.acs.users.delete({
    acs_user_id: acsUser.acs_user_id,
  });

  // Wait until each ACS user has been deleted.
  // You can watch for acs_user.deleted events.
  
}

// Step 3: List and deactivate all phones 
// associated with the user identity.

// List the phones.
const phones = await seam.phones.list({
  owner_user_identity_id: userIdentityId,
});

// Deactivate each returned phone.
for (const phone of phones) {
  await seam.phones.deactivate({
    device_id: phone.device_id,
  });

  // Wait until each phone has been deactivated.
  // You can watch for phone.deactivated events.

}

// Step 4: Delete the user identity.
await seam.userIdentities.delete({
  user_identity_id: userIdentityId,
});

Output:

// void

Ruby

Command:

user_identity_id = "22222222-2222-2222-2222-222222222222"

# Step 1: List and delete all client sessions 
# associated with the user identity.

# List the client sessions.
client_sessions = seam.client_sessions.list(
  user_identity_id: user_identity_id
)

# Delete each returned client session.
client_sessions.each do |client_session|
  seam.client_sessions.delete(
    client_session_id: client_session.client_session_id
  )
end

# Step 2: List and delete all ACS users and credentials 
# associated with the user identity.

# List the ACS users.
acs_users = seam.acs.users.list(
  user_identity_id: user_identity_id
)

acs_users.each do |acs_user|
  # For each returned ACS user, list the associated credentials.
  credentials = seam.acs.credentials.list(
    acs_user_id: acs_user.acs_user_id
  )
  
  # Delete each returned credential.
  credentials.each do |credential|
    seam.acs.credentials.delete(
      acs_credential_id: credential.acs_credential_id
    )
  
    # Wait until each credential has been deleted.
    # You can watch for acs_credential.deleted events.
  
  end
    
  # Delete each ACS user returned previously.
  seam.acs.users.delete(
      acs_user_id: acs_user.acs_user_id
  )

  # Wait until each ACS user has been deleted.
  # You can watch for acs_user.deleted events.
  
end

# Step 3: List and deactivate all phones 
# associated with the user identity.

# List the phones.
phones = seam.phones.list(
  owner_user_identity_id: user_identity_id
)

# Deactivate each returned phone.
phones.each do |phone|
  seam.phones.deactivate(
    device_id: phone.device_id
  )

  # Wait until each phone has been deactivated.
  # You can watch for phone.deactivated events.

end

# Step 4: Delete the user identity.
seam.user_identities.delete(
  user_identity_id: user_identity_id
)

Output:

nil

PHP

Command:

$user_identity_id = "22222222-2222-2222-2222-222222222222";

// Step 1: List and delete all client sessions 
// associated with the user identity.

// List the client sessions.
$client_sessions = $seam->client_sessions->list(
  user_identity_id: $user_identity_id
);

// Delete each returned client session.
foreach ($client_sessions as $client_session) {
  $seam->client_sessions->delete(
      client_session_id: $client_session->client_session_id
  );
}

// Step 2: List and delete all ACS users and credentials 
// associated with the user identity.

// List the ACS users.
$acs_users = $seam->acs->users->list(
  user_identity_id: $user_identity_id
);

foreach ($acs_users as $acs_user) {
  // For each returned ACS user, list the associated credentials.
  $credentials = $seam->acs->credentials->list(
    acs_user_id: $acs_user->acs_user_id
  );
  
  // Delete each returned credential.
  foreach ($credentials as $credential) {
    $seam->acs->credentials->delete(
      acs_credential_id: $credential->acs_credential_id
    );
  
    // Wait until each credential has been deleted.
    // You can watch for acs_credential.deleted events.
  
  }
    
  // Delete each ACS user returned previously.
  $seam->acs->users->delete(
      acs_user_id: $acs_user->acs_user_id
  );

  // Wait until each ACS user has been deleted.
  // You can watch for acs_user.deleted events.
  
}

// Step 3: List and deactivate all phones 
// associated with the user identity.

// List the phones.
$phones = $seam->phones->list(
  owner_user_identity_id: $user_identity_id
);

// Deactivate each returned phone.
foreach ($phones as $phone) {
  $seam->phones->deactivate(
    device_id: $phone->device_id
  );

  // Wait until each phone has been deactivated.
  // You can watch for phone.deactivated events.

}

// Step 4: Delete the user identity.
$seam->user_identities->delete(
  user_identity_id: $user_identity_id
);

Output:

null

C#

Command:

Coming soon!

Output:

Coming soon!