12 Mobile User Management

As a mobile app developer, you can use the Mobile Users API to get information about the currently authenticated mobile, virtual, or social user. You also can use this API to update the current mobile user's custom properties. These are the properties that you’ve have added to the realm that the member belongs to. In addition, you can use the Mobile Users Extended API to retrieve the currently authenticated mobile or virtual user's roles.

We’ll show how to make direct REST calls to these APIs. You can learn more about the APIs at REST APIs for Oracle Mobile Cloud Service.

You also can call this API from custom code, as shown in Accessing the Mobile Users API from Custom Code.

User Types

The information that the API returns depends on what type of user you are inquiring about. Here are the types of users:

Getting User Information

If your app needs user information, such as user name or first and last name, you can call the Mobile Users API to get that information.

You have two options for getting a user’s profile:

To get the currently authorized user’s profile via a direct REST call, send a GET request to /mobile/platform/users/~. Here’s an example of using cURL to send the request:

curl -i \
-X GET \ 
-u joe.doe@example.com:mypass \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/users/~
The contents of the response body depends on the user type:
  • When the user is a mobile user, the response contains the user name, first name, last name, and email address as well as the custom properties that were added to the realm that the user belongs to.

  • When the user is a virtual user, the response contains the user name.

  • When the user is a social user, the response contains the user's ID, identity provider, and access token.

Here’s an example of a response for a mobile user:

{ 
  "username": "joe.doe@example.com",  
  "firstName": "Joe",  
  "lastName": "Doe",  
  "email": "joe.doe@example.com", 
  "locale": "en", 
  "age": "39",
  "workPhone": "+19195550100", 
  "mobilePhone": "+19195550101", 
  "otherPhone": "+19195550102", 
  "avatar": "DERFSKJAKJLSAJFLKASJDFLKADJF", 
  "links": {  
    { "rel": "canonical",
      "href": "/mobile/platform/users/~"
    } 
  }
}

Here’s an example of a response for a virtual user:

{ 
  "username": "username"
}

Here’s an example of a response for a social (Facebook) user:

{
  "username": "1 :623:165",
  "mobileExtended": {
      "identityProvider": {
          "facebook": {
              "accessToken":"CAAI...YZD"
          }
      }
  }
}
For mobile users, you can limit the response to specific properties by adding a query string to the endpoint, such as fields=firstName,lastName. This argument is ignored if the user is a virtual or social user. For example, this command requests the locale property:
curl -i \
-X GET \ 
-u joe.doe@example.com:mypass \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/users/~?fields=locale

The response includes only the requested properties. For example:

{
  "locale": "en"
}

Getting User Roles

The Mobile Users Extended API lets you get a mobile or virtual user’s roles in addition to the same information that you can get from the Mobile Users API. You can’t use this API to get social user roles.

To learn how to get a user’s roles using custom code, see ums.getUserExtended(options, httpOptions).

To get the roles via a direct Mobile Users Extended REST call, you make the same request as you would with the Mobile Users API, but you use the /mobile/platform/extended endpoint instead. For example:

curl -i \
-X GET \ 
-u joe.doe@example.com:mypass \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/extended/users/~

Here’s an example of a response for a mobile user:

{
   "lastName":"Doe",
   "username":"joe.doe@example.com",
   "email":"joe.doe@example.com",
   "roles":[
      "Customer",
      "Trial"
   ],
  "links":[
        {
           "rel":"canonical",
           "href":"/mobile/extended/platform/users/joe"
        },
        {
           "rel":"self",
           "href":"/mobile/extended/platform/users/joe"
        }
  ],
   "firstName":"Joe"
}

Updating Mobile User Custom Properties

You can update a mobile user’s custom properties. These are the properties that have been added to the user schema for the user’s realm. You can’t update the standard identity properties (username, firstName, lastName, and email).

To learn how to update a mobile user’s custom properties from custom code, see ums.updateUser(fields, options, httpOptions).

To update a mobile user’s custom properties via a direct REST call, send a PATCH or PUT to /mobile/platform/users/~. Include the properties with their new values in the body of the request. For example:

curl -i \
-X PUT \ 
-u joe.doe@example.com:mypass \
-d users.json \
-H "Content-Type: application/json; charset=utf-8" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/users/~

Here’s an example of the request body:

{ 
  "locale": "en_US",
  "age": "40"
}

The response includes all the properties. For example:

{ 
  "username": "joe.doe@example.com",  
  "firstName": "Joe",  
  "lastName": "Doe",  
  "email": "joe.doe@example.com", 
  "locale": "en_US", 
  "age": "40",
  "workPhone": "+19195550100", 
  "mobilePhone": "+19195550101", 
  "otherPhone": "+19195550102", 
  "avatar": "DERFSKJAKJLSAJFLKASJDFLKADJF", 
  "links": {  
    { "rel": "canonical",
      "href": "/mobile/platform/users/~"
    } 
  }
}