Identities

The following JSON represents a typical Identity. It is referred to throughout this document as Identity; also note that BasicIdentity is frequently used when the full Identity object is not needed to identify a user.

  • Identity: Used when using Identity-specific operations
  • BasicIdentity: Used when referencing an Identity from another Object
{
  "id": "layer:///identities/1234",
  "url": "https://api.layer.com/identities/1234",
  "user_id": "1234",
  "display_name": "One Two Three Four",
  "avatar_url": "https://mycompany.co/images/1234.png",
  "first_name": "One",
  "last_name": "Four",
  "phone_number": "1-123-1234",
  "email_address": "1234@myserver.com",
  "public_key": "<RSA Key>",
  "metadata": {
    "your-key": "your-value"
  }
}
Name Type Description
id string Layer’s internal ID for this user
url string A URL for accessing the Identity via the REST API
user_id string Your application’s ID for this user
display_name string Optional display name used when rendering this user in a UI
avatar_url string Optional url to an avatar image
first_name string Optional first name of the user
last_name string Optional last name of the user
phone_number string Optional phone number for the user. Third party Webhook services may use this for SMS fallback for unread messages.
email_address string Optional email address for the user. Third party Webhook services may use this for email fallback for unread messages.
public_key string RSA public key
metadata object Custom data associated with the Identity that is viewable by all users

Note

All values that are put into the Identity object can be observed by all users of your system. Its probably fine to expose phone numbers and email addresses to coworkers, but not to contacts on a social network.

Identity objects can be created in two ways:

  • Creating a Layer Session with an Identity Token will create an Identity if one does not yet exist. The Identity Token can be used to define the following fields of your Identity:
    • user_id
    • display_name
    • avatar_url
    • public_key
    • first_name
    • last_name
  • Identities can be created, updated and deleted via the Server API; only the Server API can be used to set ALL fields of the Identity.

The id property

An ID consists of a prefix of layer:///identities/ followed by a UUID. This ID format is common across all of the Layer Platform.

This ID is a required parameter for many requests. It could also be used for indexing an in-app cache. Within Layer APIs, the full ID is used as a parameter; however, only the UUID is used if the ID is being used within a URL.

The url property

The url property specifies how to retrieve or operate upon the Identity via the REST API.

The metadata property

Metadata allows custom data to be associated with a Conversation. For example, there is no title property in the Conversation Object. If your Conversations need a title to share between all participants and render as part of your view, you can add a title property to the metadata and share it that way.

All values in metadata must be strings or objects. The following metadata is valid:

{
  "metadata": {
    "joined": "10-10-2010 10:05:00",
    "rank": "35",
    "is_active": "true",
    "preferences": {
      "background_color": "red",
      "nose": "long"
    }
  }
}
Changelogs Basic Identity