Manage App Users and Sessions
Each app has a user
model that represents users that can enroll in the application. Whenever a user
object is created, additional metadata is stored to facilitate enrollment and session management.
A single user may have one or more sessions. A session represents a single device that is (or was) signed in.
Parameters
To retrieve, create, update or delete mobile users, follow the instructions in these sections of the documentation for your mobile user object type (e.g. user):
Deleting the user object will lock the user and wipe all app data from the user's enrolled devices. This operation is irreversible.
User and Sessions API
/api/v4/
backend-deployment-id
/users/
user-id
/sessions/
session-id
/re-authenticate
POST
List all users
API:
GET BASE-URL/api/v4/backend-deployment-id/users[?limit=x&skip=y]
Sample request:
GET BASE-URL/api/v4/533bda53027894f69b001055/users?limit=2&skip=0
Sample response:
{
"total": 47,
"count": 2,
"more": true,
"objects": [
{
"id": "c8c8c4f8-5013-11e7-a8c7-04017e679e01",
"last_connected_at": "2017-08-18T13:33:23Z",
"enrolled": false,
"locked": false,
"sessions": [
{
"id": "9469407e-8417-11e7-825d-040151508301",
"state": "LOCKED",
"last_authenticated_at": "2017-08-18T13:17:26Z",
"created_at": "2017-08-18T13:17:26Z",
"signed_out_at": "2017-08-18T13:33:23Z",
"last_connected_at": "2017-08-18T13:33:23Z",
"container": {
"version": "20.6.1",
"bundle_id": "xyz.appinstall.myapp",
"platform": "IOS"
},
"runtime": {
"version": "4.82.0"
},
"device": {
"id": "1234-1234-1234-1234"
},
"label": "Apple iPhone7,2",
"sync_status": {
"last_full_sync": "2018-07-31T12:17:58Z"
}
}
]
},
{
"id": "5571fb26-54f7-11e7-a8f8-040151508301",
"last_connected_at": "2017-08-23T10:12:57Z",
"enrolled": true,
"locked": false,
"sessions": [
{
"id": "066b26c4-8418-11e7-9ba9-04017e679e01",
"state": "ENROLLED",
"last_authenticated_at": "2017-08-18T13:20:37Z",
"created_at": "2017-08-18T13:20:37Z",
"signed_out_at": null,
"last_connected_at": "2017-08-23T10:12:57Z",
"container": {
"version": "20.6.1",
"bundle_id": "xyz.appinstall.myapp",
"platform": "ANDROID"
},
"runtime": {
"version": "4.82.0"
},
"device": {
"id": "2345-2345-2345-2345"
},
"label": "Sony C6903"
},
{
"id": "556ed8a6-54f7-11e7-a8f8-040151508301",
"state": "LOCKED",
"last_authenticated_at": null,
"created_at": null,
"signed_out_at": "2017-08-18T13:20:30Z",
"last_connected_at": "2017-06-19T14:19:39Z",
"container": {
"version": "20.6.1",
"bundle_id": "xyz.appinstall.myapp",
"platform": "CHROME"
},
"runtime": {
"version": "4.82.0"
},
"device": {
"id": "3456-3456-3456-3456"
},
"label": "Chrome"
}
]
}
]
}
Get single user
API:
GET /api/v4/backend-deployment-id/users/user-id
Sample request:
GET BASE-URL/api/v4/533bda53027894f69b001055/users/c8c8c4f8-5013-11e7-a8c7-04017e679e01
Sample response:
{
"id": "c8c8c4f8-5013-11e7-a8c7-04017e679e01",
"last_connected_at": "2017-08-18T13:33:23Z",
"enrolled": false,
"locked": false,
"sessions": [
{
"id": "9469407e-8417-11e7-825d-040151508301",
"state": "LOCKED",
"last_authenticated_at": "2017-08-18T13:17:26Z",
"created_at": "2017-08-18T13:17:26Z",
"signed_out_at": "2017-08-18T13:33:23Z",
"last_connected_at": "2017-08-18T13:33:23Z",
"container": {
"version": "20.6.1",
"bundle_id": "xyz.appinstall.myapp",
"platform": "IOS"
},
"runtime": {
"version": "4.82.0"
},
"device": {
"id": "3456-3456-3456-3456"
},
"label": "Apple iPhone7,2",
"sync_status": {
"last_full_sync": "2018-07-31T12:17:58Z"
}
}
]
}
Get single session
API:
GET /api/v4/backend-deployment-id/users/user-id/sessions/session-id
Sample request:
GET BASE-URL/api/v4/533bda53027894f69b001055/users/c8c8c4f8-5013-11e7-a8c7-04017e679e01/sessions/9469407e-8417-11e7-825d-040151508301
Sample response:
{
"id": "9469407e-8417-11e7-825d-040151508301",
"state": "LOCKED",
"last_authenticated_at": "2017-08-18T13:17:26Z",
"created_at": "2017-08-18T13:17:26Z",
"signed_out_at": "2017-08-18T13:33:23Z",
"last_connected_at": "2017-08-18T13:33:23Z",
"container": {
"version": "20.6.1",
"bundle_id": "xyz.appinstall.myapp",
"platform": "IOS"
},
"runtime": {
"version": "4.82.0"
},
"device": {
"id": "3456-3456-3456-3456"
},
"label": "Apple iPhone7,2",
"sync_status": {
"last_full_sync": "2018-07-31T12:17:58Z"
}
}
Fields:
state
ENROLLED
: Currently enrolled.
LOCKED
: Locked via backend, API, or from the device. Will direct user to the login screen on next connect.
RESET
: Like locked, but will force a data wipe the next time the device connects.
NEVER_ENROLLED
: Only for legacy data.
last_connected_at
Updated every time the device connects via an API call, such as sync or data upload.
created_at
First enrollment date for this session.
last_authenticated_at
Date of the last enrollment call. Should be close to created_at
if this is the first enrollment (may not match exactly).
signed_out_at
Date of last sign out (when the state changed to LOCKED
or RESET
). Stays present when the session enrolls again.
Apart from last_connected_at
, these values only change when the user enrolls or the session is "locked". Note that in typical cases, the same session is used over multiple enrollments if the same device is used, but a new session is created if the user enrolls using a different device.
Lock user
Locking the user will automatically disable the application on all of their devices, as well as prevent them from logging in again.
If wipe
is true, all application data on the device will be permanently deleted. This can include any data or attachments that have not uploaded to the JourneyApps Backend yet. This action cannot be undone.
API:
POST /api/v4/backend-deployment-id/users/user-id/lock
{"wipe": true/false}
Or use the batch operation:
{
"method": "users/lock",
"user_id": "...",
"wipe": true/false
}
Note: the wipe parameter is required.
The response code is 204 if successful.
Unlock user
Allow a locked user to log in again.
API:
POST /api/v4/backend-deployment-id/users/user-id/unlock
Or use the batch operation:
{
"method": "users/unlock",
"user_id": "..."
}
The response code is 204 if successful.
Wipe session
This will permanently delete all application data from the specific device. This can include any data or attachments that have not uploaded to the JourneyApps Backend yet. This action cannot be undone.
This does not affect any other sessions, and the user will still be able to log in.
API:
POST /api/v4/backend-deployment-id/users/user-id/sessions/session-id/wipe
Or use the batch operation:
{
"method": "users/sessions/wipe",
"user_id": "...",
"session_id: "..."
}
The response code is 204 if successful.
Re-authenticate session
This disables the session, requiring the user to log in again. No data is deleted on the device.
API:
POST /api/v4/backend-deployment-id/users/user-id/sessions/session-id/re-authenticate
Or use the batch operation:
{
"method": "users/sessions/re-authenticate",
"user_id": "...",
"session_id: "..."
}
The response code is 204 if successful.
Generate Authentication Token
Generate a temporary token that can be used for enrollment.
Authentication tokens expire 5 minutes after being created.
If the "multiple devices per user" flag is not enabled for the application, this can only be used to enroll one user at a time.
API:
POST /api/v4/backend-deployment-id/users/user-id/authentication-token
Or use the batch operation:
{
"method": "users/authentication-token",
"user_id": "..."
}
Sample Response:
{
"token": "12345678",
"url": "https://embark.mobi/enroll?h=internal-testing.journeyapps.com&k=12345678&t=j"
}
Last updated