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 = "[e-mail]",
  phone_number = "[phone]",
  full_name = "Jean Doe"
)

Output:

UserIdentity(
  user_identity_id='22222222-2222-2222-2222-222222222222',
  user_identity_key='jean_doe',
  email_address='[e-mail]',
  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": "[e-mail]",
  "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": "[e-mail]",
    "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: "[e-mail]",
  phone_number: "[phone]",
  full_name: "Jean Doe",
});

Output:

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

Ruby

Command:

seam.user_identities.create(
  user_identity_key: "jean_doe",
  email_address: "[e-mail]",
  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="[e-mail]"
  phone_number="[phone]"
  display_name="Jean Doe"
  full_name="Jean Doe"
  ...
>

PHP

Command:

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

Output:

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

C#

Command:

Coming soon!

Output:

Coming soon!

Java

Command:

Coming soon!

Output:

Coming soon!

Go

Command:

userIdentity, uErr := client.UserIdentities.Create(context.Background(), &api.UserIdentitiesCreateRequest{
  UserIdentityKey: api.String("jean_doe"),
  EmailAddress: api.String("[e-mail]"),
  PhoneNumber: api.String("[phone]"),
  FullName: api.String("Jean Doe"),
})

if uErr != nil {
    return uErr
}

fmt.Println(userIdentity)
return nil

Output:

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

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 = "[e-mail]"
)

acs_user = seam.acs.users.get(
  email_address = "[e-mail]"
)

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\": \"[e-mail]\"
}")

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


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: "[e-mail]",
});

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

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: "[e-mail]"
)

acs_user = seam.acs.users.get(
  email_address: "[e-mail]"
)

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: "[e-mail]",
);

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

$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!

Java

Command:

Coming soon!

Output:

Coming soon!

Go

Command:

userIdentity, uErr := client.UserIdentities.Get(context.Background(), &api.UserIdentitiesGetRequest{
  EmailAddress: api.String("[e-mail]"),
})

if uErr != nil {
    return uErr
}

acsUser, uErr := client.Acs.Users.Get(context.Background(), &acs.UsersGetRequest{
  EmailAddress: api.String("[e-mail]"),
})

if uErr != nil {
    return uErr
}

_, uErr := client.UserIdentities.AddAcsUser(context.Background(), &useridentities.UserIdentitiesAddAcsUserRequest{
    UserIdentityId: acs_user.UserIdentityId,
    AcsUserId: acs_user.AcsUserId,
})

if uErr != nil {
    return uErr
}

return nil

Output:

nil

---

Removing a User Identity

To delete a user identity, you must first delete any ACS credentials, ACS users, and enrollment automations 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 delete all enrollment automations 
  # associated with the user identity.
  
  # List the enrollment automations.
  enrollment_automations = await seam.user_identities.enrollment_automations.list(
      user_identity_id=user_identity_id
  )

  # Delete the enrollment automations.
  for automation in enrollment_automations:
    await seam.user_identities.enrollment_automations.delete(
      enrollment_automation_id=automation['enrollment_automation_id']
    )

  await asyncio.gather(*[
    wait_for_enrollment_automation_deleted(automation)
    for automation in enrollment_automations
  ])

  # Step 4: 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 5: 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_enrollment_automation_deleted(enrollment_automation):
  await wait_for_event(
    'enrollment_automation.deleted',
    lambda event: 'enrollment_automation_id' in event and
                  event.enrollment_automation_id == enrollment_automation.enrollment_automation_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 delete all enrollment automations 
// associated with the user identity.

// List the enrollment automations.
const enrollmentAutomations = await seam.userIdentities.enrollmentAutomations.list({
  user_identity_id: userIdentityId,
});

// Delete each returned enrollment automation.
for (const enrollmentAutomation of enrollmentAutomations) {
  await seam.userIdentities.enrollmentAutomations.delete({
    enrollment_automation_id: enrollmentAutomation.enrollment_automation_id,
  });

  // Wait until each enrollment automation has been deleted.
  // You can watch for enrollment_automation.deleted events.

}

// Step 4: 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 5: 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 delete all enrollment automations 
# associated with the user identity.

# List the enrollment automations.
enrollment_automations = seam.user_identities.enrollment_autoations.list(
  user_identity_id: user_identity_id
)

# Delete each returned enrollment automation.
enrollment_automations.each do |enrollment_automation|
  seam.user_identities.enrollment_automations.delete(
    enrollment_automation_id: enrollment_automation.enrollment_automation_id
  )

  # Wait until each enrollment automation has been deleted.
  # You can watch for enrollment_automation.deleted events.

end

# Step 4: 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 5: 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 delete all enrollment automations 
// associated with the user identity.

// List the enrollment automations.
$enrollment_automations = $seam->user_identities->enrollment_automations->list(
  user_identity_id: $user_identity_id
);

// Delete each returned enrollment automation.
foreach ($enrollment_automations as $enrollment_automation) {
  $seam->user_identities->enrollment_automations->delete(
    enrollment_automation_id: $enrollment_automation->enrollment_automation_id
  );

  // Wait until each enrollment automation has been deleted.
  // You can watch for enrollment_automation.deleted events.

}

// Step 4: 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 5: Delete the user identity.
$seam->user_identities->delete(
  user_identity_id: $user_identity_id
);

Output:

null

C#

Command:

Coming soon!

Output:

Coming soon!

Java

Command:

Coming soon!

Output:

Coming soon!

Go

Command:

userIdentityID := "22222222-2222-2222-2222-222222222222"

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

// List the client sessions.
clientSessions, uErr := seam.ClientSessions.List(
  context.Background(),
  userIdentityID
)
if uErr != nil {
  return uErr
}

// Delete each returned client session.
for _, clientSession := range clientSessions {
  uErr := seam.ClientSessions.Delete(
    context.Background(),
    clientSession.ClientSessionID
  )
  if uErr != nil {
    return uErr
  }
}

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

// List the ACS users.
acsUsers, uErr := seam.ACS.Users.List(
  context.Background(),
  userIdentityID
)
if uErr != nil {
  return uErr
}

for _, acsUser := range acsUsers {
  // For each returned ACS user, list the associated credentials.
  credentials, uErr := seam.ACS.Credentials.List(
    context.Background(),
    acsUser.ACSUserID
  )
  if uErr != nil {
    return uErr
  }
  
  // Delete each returned credential.
  for _, credential := range credentials {
    uErr := seam.ACS.Credentials.Delete(
      context.Background(),
      credential.ACSCredentialID
    )
    if uErr != nil {
      return uErr
    }

    // Wait until each credential has been deleted.
    // You can watch for acs_credential.deleted events.
  }
    
  // Delete each ACS user returned previously.
  uErr = seam.ACS.Users.Delete(
    context.Background(),
    acsUser.ACSUserID
  )
  if uErr != nil {
    return uErr
  }

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

// Step 3: List and delete all enrollment automations 
// associated with the user identity.

// List the enrollment automations.
enrollmentAutomations, uErr := seam.UserIdentities.EnrollmentAutomations.List(
  context.Background(),
  userIdentityID
)
if uErr != nil {
  return uErr
}

// Delete each returned enrollment automation.
for _, enrollmentAutomation := range enrollmentAutomations {
  uErr := seam.UserIdentities.EnrollmentAutomations.Delete(
    context.Background(),
    enrollmentAutomation.EnrollmentAutomationID
  )
  if uErr != nil {
    return uErr
  }

  // Wait until each enrollment automation has been deleted.
  // You can watch for enrollment_automation.deleted events.
}

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

// List the phones.
phones, uErr := seam.Phones.List(
  context.Background(),
  userIdentityID
)
if uErr != nil {
  return uErr
}

// Deactivate each returned phone.
for _, phone := range phones {
  uErr := seam.Phones.Deactivate(
    context.Background(),
    phone.DeviceID
  )
  if uErr != nil {
    return uErr
  }

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

// Step 5: Delete the user identity.
uErr = seam.UserIdentities.Delete(
  context.Background(),
  userIdentityID
)
if uErr != nil {
  return uErr
}

return nil

Output:

nil