Managing Phones for a User Identity

Learn how to manage the phones associated with a user identity.

An app user may have several phones. When they sign into their account on your mobile application, it is important that additional phones also provide access. Seam facilitates this access by registering each phone within the user identity and synchronizing mobile credentials across these phones. Further, Seam provides a feature to deactivate a phone if an app user loses it.

---

App User New Phone Process

When an app user signs in to a new phone, Seam can automatically set up the new phone, generate matching credentials, and issue these credentials. To facilitate this capability, you must issue a multi-phone sync credential when creating a mobile credential.

---

App User Lost Phone Process

If an app user loses their phone or wants to deactivate it, you can deactivate the phone. Seam then automatically invalidates the stored credentials on their deactivated phone.

To deactivate a phone, provide the ID of the phone. When a phone is deactivated, Seam also revokes all the credentials issued to the deactivated phone. Seam also removes the associated ACS credentials from the ACS.

Python

Command:

seam.phones.deactivate(
  device_id = lost_phone_id
)

Output:

None    

cURL (bash)

Request:

curl -X 'POST' \
  'https://connect.getseam.com/phones/deactivate' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"device_id\": \"${lost_phone_id}\"
}"

Response:

{
  "ok": true
}

JavaScript

Command:

await seam.phones.deactivate({
  device_id: lostPhoneId,
});

Output:

// void

Ruby

Command:

seam.phones.deactivate(
  device_id: lost_phone_id
)

Output:

nil

PHP

Command:

$seam->phones->deactivate(
  device_id: $lost_phone_id,
);

Output:

null

C#

Command:

Coming soon!

Output:

Coming soon!

Java

Command:

Coming soon!

Output:

Coming soon!

Go

Command:

_, uErr := client.Phones.Deactivate(
  context.Background(),
  &api.PhonesDeactivateRequest{
    DeviceId: lostPhoneId,
})

if uErr != nil {
    return uErr
}

return nil

Output:

nil

---

Retrieving Phones for a User Identity

To retrieve the list of phones that the mobile app user has used to sign in to their account, use the List Phones endpoint and include the ID of the user identity.

Python

Command:

seam.phones.list(
  owner_user_identity_id = user_identity.id
)

Output:

[
  Phone(
    device_id='22222222-2222-2222-2222-444444444444',
    device_type='android_phone',
    created_at='2025-01-01T10:40:00+00:00',
    ...
  )
  Phone(
    device_id='22222222-2222-2222-2222-555555555555',
    device_type='ios_phone',
    created_at='2025-01-02T10:40:00+00:00',
    ...
  )
  ...
]

cURL (bash)

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/phones/list' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"owner_user_identity_id\": \"${user_identity_id}\"
}"

Response:

{
  "phones": [
    {
      "device_id": "22222222-2222-2222-2222-444444444444",
      "device_type": "android_phone",
      "created_at": "2025-01-01T10:40:00+00:00",
      ...
    },
    {
      "device_id": "22222222-2222-2222-2222-555555555555",
      "device_type": "ios_phone",
      "created_at": "2025-01-02T10:40:00+00:00",
      ...
    },
    ...
  ],
  "ok": true
}

JavaScript

Command:

await seam.phones.list({
  owner_user_identity_id: user_identity.id,
});

Output:

[
  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  },
  {
    "device_id": "22222222-2222-2222-2222-555555555555",
    "device_type": "ios_phone",
    "created_at": "2025-01-02T10:40:00+00:00",
    ...
  },
  ...
]

Ruby

Command:

seam.phones.list(
  owner_user_identity_id: user_identity.id,
)

Output:

[
  <Seam::Resources::Phone:0x005f0
    device_id="22222222-2222-2222-2222-444444444444"
    device_type="android_phone"
    created_at="2025-01-01T10:40:00+00:00"
    ...
  >,
  <Seam::Resources::Phone:0x005f0
    device_id="22222222-2222-2222-2222-555555555555"
    device_type="ios_phone"
    created_at="2025-01-02T10:40:00+00:00"
    ...
  >,
  ...
]

PHP

Command:

$seam->phones->list(
  owner_user_identity_id: $user_identity->id
);

Output:

[
  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  },
  {
    "device_id": "22222222-2222-2222-2222-555555555555",
    "device_type": "ios_phone",
    "created_at": "2025-01-02T10:40:00+00:00",
    ...
  },
  ...
]

C#

Command:

Coming soon!

Output:

Coming soon!

Java

Command:

Coming soon!

Output:

Coming soon!

Go

Command:

phones, uErr := client.phones.List(
  context.Background(), &api.PhonesListRequest{
    owner_user_identity_id: userIdentity.id,
})

if uErr != nil {
    return uErr
}

for _, phone := range phones {
  fmt.Println(phone)
}
    
return nil

Output:

[
  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  },
  {
    "device_id": "22222222-2222-2222-2222-555555555555",
    "device_type": "ios_phone",
    "created_at": "2025-01-02T10:40:00+00:00",
    ...
  },
  ...
]

---

Retrieving a Phone by ID

Coming soon!

To retrieve a phone by its ID, use the Get Phone endpoint and include the device_id of the phone.

Python

Command:

seam.phones.get(
  device_id = "22222222-2222-2222-2222-444444444444"
)

Output:

Phone(
  device_id='22222222-2222-2222-2222-444444444444',
  device_type='android_phone',
  created_at='2025-01-01T10:40:00+00:00',
  ...
)

cURL (bash)

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/phones/get' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "22222222-2222-2222-2222-444444444444"
}'

Response:

{
  "phone": {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  },
  "ok": true
}

JavaScript

Command:

await seam.phones.list({
  owner_user_identity_id: user_identity.id,
});

Output:

[
  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  },
  {
    "device_id": "22222222-2222-2222-2222-555555555555",
    "device_type": "ios_phone",
    "created_at": "2025-01-02T10:40:00+00:00",
    ...
  },
  ...
]

Ruby

Command:

seam.phones.list(
  owner_user_identity_id: user_identity.id,
)

Output:

[
  <Seam::Resources::Phone:0x005f0
    device_id="22222222-2222-2222-2222-444444444444"
    device_type="android_phone"
    created_at="2025-01-01T10:40:00+00:00"
    ...
  >,
  <Seam::Resources::Phone:0x005f0
    device_id="22222222-2222-2222-2222-555555555555"
    device_type="ios_phone"
    created_at="2025-01-02T10:40:00+00:00"
    ...
  >,
  ...
]

PHP

Command:

$seam->phones->list(
  owner_user_identity_id: $user_identity->id
);

Output:

[
  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  },
  {
    "device_id": "22222222-2222-2222-2222-555555555555",
    "device_type": "ios_phone",
    "created_at": "2025-01-02T10:40:00+00:00",
    ...
  },
  ...
]

C#

Command:

Coming soon!

Output:

Coming soon!

Java

Command:

Coming soon!

Output:

Coming soon!

Go

Command:

phones, uErr := client.phones.List(
  context.Background(), &api.PhonesListRequest{
    owner_user_identity_id: userIdentity.id,
})

if uErr != nil {
    return uErr
}

for _, phone := range phones {
  fmt.Println(phone)
}
    
return nil

Output:

[
  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  },
  {
    "device_id": "22222222-2222-2222-2222-555555555555",
    "device_type": "ios_phone",
    "created_at": "2025-01-02T10:40:00+00:00",
    ...
  },
  ...
]