Users endpoints

Method HTTP request Description
Create identity POST /apps/:app_uuid/users/:user_id/identity Register an Identity with Layer
Update identity PATCH /apps/:app_uuid/users/:user_id/identity Update parameters for an Identity
Replace identity PUT /apps/:app_uuid/users/:user_id/identity Replace the entire identity object
Get identity GET /apps/:app_uuid/users/:user_id/identity Get the identity data stored on Layer
Delete identity DELETE /apps/:app_uuid/users/:user_id/identity Delete an identity from Layer
Get badge count GET /apps/:app_uuid/users/:user_id/badge Get the computed badge count for the specified user
Set badge count PUT /apps/:app_uuid/users/:user_id/badge Set a badge value for external content
Update block list PATCH /apps/:app_uuid/users/:owner_user_id Block or unblock users
Get block list GET /apps/:app_uuid/users/:owner_user_id/blocks Get list of users blocked by the owner
Set suspension PATCH /apps/:app_uuid/users/:user_id Suspend or unsuspend a user
Get suspension status GET /apps/:app_uuid/users/:user_id Check if a user is suspended
Set session TTL PATCH /apps/:app_uuid Set the amount of time before a session expires
Expire user sessions DELETE /apps/:app_uuid/users/:user_id/sessions Expire all sessions for a user

Create identity

You can create an Identity object when authenticating via the Identity Token. Alternately, you can register an Identity with Layer at a later time using this endpoint. Creating an Identity will not count towards your monthly users.

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with
display_name string Name to show on-screen for user
avatar_url string (optional) URL to the user’s profile photo
first_name string (optional) First name for user
last_name string (optional) Last name for user
phone_number string (optional) Phone number for user
email_address string (optional) Email for user
public_key string (optional) Public encryption key for end-to-end encryption
metadata object (optional) Arbitrary key-value metadata. Values must be strings, nested objects are not supported.

HTTP request:

POST/apps/:app_uuid/users/:user_id/identity

Example:

{
    "display_name": "Frodo the Dodo",
    "avatar_url": "http://sillylordoftheringspictures.com/frodo-riding-a-dodo.png",
    "first_name": "Frodo",
    "last_name": "Baggins",
    "phone_number": "13791379137",
    "email_address": "frodo@sillylordoftheringspictures.com",
    "metadata": {
        "level": "35",
        "race": "Dodo"
    }
}
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity\
 -d '{"display_name":"Frodo the Dodo","avatar_url":"http://sillylordoftheringspictures.com/frodo-riding-a-dodo.png","first_name":"Frodo","last_name":"Baggins","phone_number":"13791379137","email_address":"frodo@sillylordoftheringspictures.com","metadata":{"level":"35","race":"Dodo"}}'

Possible responses:

Identity created successfully
Status: 201 (Created)
(Empty body)

Update identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with
operation string The type of operation; “set” is the only allowed value for this endpoint
property string The property to change
value string New value to set

HTTP request:

PATCH/apps/:app_uuid/users/:user_id/identity

Example:

[
    {
        "operation": "set",
        "property": "last_name",
        "value": "Dodo"
    },
    {
        "operation": "set",
        "property": "phone_number",
        "value": ""
    },
    {
        "operation": "set",
        "property": "metadata.level",
        "value": "2"
    }
]
curl -X PATCH \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/vnd.layer-patch+json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity\
 -d '[{"operation":"set","property":"last_name","value":"Dodo"},{"operation":"set","property":"phone_number","value":""},{"operation":"set","property":"metadata.level","value":"2"}]'

Possible responses:

Identity updated successfully
Status: 204 (No Content)
(Empty body)

Replace identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with
display_name string Name to show on-screen for user
avatar_url string (optional) URL to the user’s profile photo
first_name string (optional) First name for user
last_name string (optional) Last name for user
phone_number string (optional) Phone number for user
email_address string (optional) Email for user
public_key string (optional) Public encryption key for end-to-end encryption
metadata object (optional) Arbitrary key-value metadata. Values must be strings, nested objects are not supported.

HTTP request:

PUT/apps/:app_uuid/users/:user_id/identity

Example:

curl  -X PUT \
      -H 'Accept: application/vnd.layer+json; version=1.1' \
      -H 'Authorization: Bearer TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{"display_name": "Frodo the Dodo", "first_name": "Frodo"}' \
      https://api.layer.com/apps/<APP_UUID>/users/<USER_ID>/identity

Possible responses:

Identity updated successfully
Status: 204 (No Content)
(Empty body)

Get identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with

HTTP request:

GET/apps/:app_uuid/users/:user_id/identity

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity

Possible responses:

Got identity | Status: 200 (OK)

Identity

Delete identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with

HTTP request:

DELETE/apps/:app_uuid/users/:user_id/identity

Example:

curl -X DELETE \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity

Possible responses:

Identity deleted successfully
Status: 204 (No Content)
(Empty body)

Discussion

Note

Deleting an identity that is referenced by a pre-existing conversation or message has no impact on those entities.

Get badge count

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to get the counts for

HTTP request:

GET/apps/:app_uuid/users/:user_id/badge

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/badge

Possible responses:

Got badge count | Status: 200 (OK)

{
    "external_unread_count": 13,
    "unread_conversation_count": 10,
    "unread_message_count": 50
}

Discussion

Layer maintains an internal service dedicated to managing accurate badge counts that are included in push notifications for iOS users. This is necessary because iOS does not provide strong guarantees about when an application will be woken up in the background in response to a remote notification, so computing counts device side delivers a sub-optimal user experience.

Within the Developer Dashboard, you can configure the badging mode to show:

  • Unread Conversations count
  • Unread Messages count
  • External count only
  • Nothing (disable badging)

You can also choose to sum the count of unread Announcements with any of the above badging modes.

Note

We don’t recommend reading Layer badge values and mirroring it via an external push service, since message data is fast-moving and the count could change in the meantime.

Set badge count

Many applications involve badge counts for data beyond Layer Messages and Conversations. To accommodate these cases, the Server API exposes endpoints for managing an external badge count. The external badge count is an integer value that is summed with the Layer (internal)L badge count and sent along with each push notification that originates from Layer. When a badge is set for a user with one or more iOS devices, a push notification is immediately dispatched to update the badge with the latest state.

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with
external_unread_count integer The external count to set

HTTP request:

PUT/apps/:app_uuid/users/:user_id/badge

Example:

{
    "external_unread_count": 13
}
curl -X PUT \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/badge\
 -d '{"external_unread_count":13}'

Possible responses:

External count set successfully
Status: 204 (No Content)
(Empty body)

Update block list

This endpoint allows you to block or unblock multiple users in one request to align with your application-level blocking.

Parameters:

Name Type Description
operation string The type of operation; possible values are “add” or “remove”
property string “blocks” is the only accepted value for this endpoint
id string Identity ID of the user to be blocked/unblocked

HTTP request:

PATCH/apps/:app_uuid/users/:owner_user_id

Example:

[
    {
        "operation": "add",
        "property": "blocks",
        "id": "layer:///identities/blockMe1"
    },
    {
        "operation": "add",
        "property": "blocks",
        "id": "layer:///identities/blockMe2"
    },
    {
        "operation": "remove",
        "property": "blocks",
        "id": "layer:///identities/unblockMe"
    }
]
curl -X PATCH \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/vnd.layer-patch+json' \
     https://api.layer.com/apps/<app_uuid>/users/<owner_user_id>\
 -d '[{"operation":"add","property":"blocks","id":"layer:///identities/blockMe1"},{"operation":"add","property":"blocks","id":"layer:///identities/blockMe2"},{"operation":"remove","property":"blocks","id":"layer:///identities/unblockMe"}]'

Possible responses:

Request enqueued
Status: 202 (Accepted)
(Empty body)

Discussion

The Server API allows you to manage a Block List for each user to align with your application-level blocking. A Block List is “owned” by a user, and contains a list of other users the owner doesn’t wart to communicate with. More information about blocking is available in our Knowledge Base.

This endpoint supports bulk operations (there is no limit to the number of operations you can include in the request). We enqueue these requests and process them asynchronously. As a result, blocking may take a non-zero amount of time to take effect, and we return a 202 (Accepted) status code rather than 204 (No content) to reflect this.

A set operation can be used to clear the Block List:

[
  {"operation": "set", "property": "blocks", "value": []}
]

Get block list

Parameters:

Name Type Description
app_uuid string Your Layer App ID
owner_user_id string ID of the user requesting the block/unblock

HTTP request:

GET/apps/:app_uuid/users/:owner_user_id/blocks

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<owner_user_id>/blocks

Possible responses:

Got block list | Status: 200 (OK)

[
    BasicIdentity,
    BasicIdentity
]

Set suspension

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to suspend
operation string “set” is the only supported value for this endpoint
property string “suspended” is the only supported value for this endpoint
value string Set to trueto suspend the user, false to unsuspend

HTTP request:

PATCH/apps/:app_uuid/users/:user_id

Example:

[
    {
        "operation": "set",
        "property": "suspended",
        "value": true
    }
]
curl -X PATCH \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/vnd.layer-patch+json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>\
 -d '[{"operation":"set","property":"suspended","value":true}]'

Possible responses:

Suspended/unsuspended successfully
Status: 202 (Accepted)
(Empty body)

Discussion

Suspending a user temporarily or permanently prevents that user authenticating or resuming an authenticated session. The feature works by clearing all session tokens for the target user and refusing to create new sessions upon successful authentication.

Note

Suspension changes do not take effect immediately due to caching. Please allow up to 5 minutes for changes to take effect.

Get suspension status

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to check

HTTP request:

GET/apps/:app_uuid/users/:user_id

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>

Possible responses:

Got suspension status | Status: 200 (OK)

{
    "identity": Identity,
    "suspended": false
}

Set session TTL

Successful Layer authentication results in a session that expires after a period of time. You may want to control the default session TTL (time to live) for your application. This is useful for testing your authentication implementation.

Parameters:

Name Type Description
app_uuid string Your Layer App ID
operation string “set” is the only supported value for this endpoint
property string “session_ttl_in_seconds” is the only supported value for this endpoint
value integer TTL value to set, in seconds. Acceptable range is 30 – 31536000 (1 year)

HTTP request:

PATCH/apps/:app_uuid

Example:

[
    {
        "operation": "set",
        "property": "session_ttl_in_seconds",
        "value": 3600
    }
]
curl -X PATCH \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/vnd.layer-patch+json' \
     https://api.layer.com/apps/<app_uuid>\
 -d '[{"operation":"set","property":"session_ttl_in_seconds","value":3600}]'

Possible responses:

TTL set successfully
Status: 202 (Accepted)
(Empty body)

Discussion

The default session expiration time is 5 minutes for apps using a staging ID and 30 days for apps using a production ID. Once a session expires, your client will have to run through the authentication flow again before any additional Layer operations will succeed. This reauthentication can usually happen transparently, without any user-facing interactions or indications.

Expire user sessions

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to expire sessions for

HTTP request:

DELETE/apps/:app_uuid/users/:user_id/sessions

Example:

curl -X DELETE \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/sessions

Possible responses:

Sessions deleted successfully
Status: 204 (No Content)
(Empty body)