Authentication and User Discovery

Use of the Magnet Messaging REST APIs requires application credentials. The following describes how to you can get credentials and authenticate the app and how to discover users using the REST APIs.

Getting Your Credentials

To ensure that the REST APIs are used appropriately, only those applications that know the client-id and client-secret are allowed to access Magnet Max APIs. This also means that APIs are targeted to a user's app, not to a specific user per-se.

An authentic "Client ID" and "Client Secret" are the necessary credentials to get the access token which is required to make any REST API call. These credentials can be found in the Magnet Max Console.

After logging into the Magnet Studio Console, you should select the target app and go to the Settings menu. From there you should locate the "OAuth Client Id and OAuth Secret as seen in the following figure.

oauth_keys

Authentication

An application-specific OAuth token is required for using the REST APIs. The following will describe the step-by-step process for obtaining an OAuth token. Currently, the MMS-DEVICE-ID property must always be set. You can input any value you like into the property.

  1. Log in with User Credentials:

    • Path
      POST https://<server>/mobile/api/com.magnet.server/user/session?grant_type=password&username=<username>&password=<password>&client_id=<client-id>&scope=public</code>
    • Sample Request
      curl -X POST \
-H "MMS-DEVICE-ID:1111-2222-3333-4444" \
-d "grant_type=password&username=QuickstartUser2&password=QuickstartUser2&client_id=4fdb5008-1f6d-4cc1-80b9-deca1352cd5e&scope=public" \
https://<server>/mobile/api/com.magnet.server/user/session
    • Sample Response
      {
"token_type": "USER",
"expires_in": 7200,
"access_token": "DdLLoGLYmi0cUSWDVLG58jM3clIaVH1AlBWr5a2zM8WVuO_WVRoqfj995FFVkZyExIv8OJWaK3aoVIm75n2BgOrEK76WwTeQ7pzdvO-F3olw34jHP7fxkDrayGQVWSviIK95SbNhB8r6ojwRbPaNngbLprBxMxNLoHDA56Hx7Ctf-JWnRYXDBshrWWkagVxc5u5lhjxvUjQV7t_4YIjlCkh_gDxRN66HUte47vUGu2BXAS9UphYEC9E5q29BrkYQcLS94UtOtsOWyjbhiAV0bFo9drBToTrwz-RZWKzPUdc",
"user": {
  "userIdentifier": "8a00a8b550baaeb30150bae12b8f000c",
  "clientId": "7d47bc1f-2e12-48b3-bba5-97f8fb9d6a1d",
  "firstName": "QuickstartUser2",
  "lastName": "QuickstartUser2",
  "userName": "quickstartuser2",
  "password": "n/a",
  "userRealm": "DB",
  "userStatus": "ACTIVE",
  "roles": [
    "USER"
  ],
  "otpCode": "n/a",
  "userAccountData": {}
}
}
    • Parameters
      grant_type the type of grant being presented in exchange for an access token
      username username used to login
      password password used to login
      client-id the oauth client id found in the Settings page of the console
      scope the scope of the access request

  2. Extract the access_token for all subsequent API calls:

    All REST API calls will require an Authorization header with the Bearer token. For example:

     curl -X POST -H "Authorization: Bearer <access token>"  .......

User Discovery

You can search for all users or a specific user as described below.

  1. Get All Users:

    • Path

      GET https://<server>/mobile/api/com.magnet.server/user/all

    • Sample Request

      curl -X GET \
 -H "Authorization: Bearer BdnmKoeKRY33fhSIW0lUG8Kz7jUdluEsvkff0SaPGL6w0LYRhV9CyGehPOt3caEXJh69C3257lPYbh_YnpRwy36DHt74PkC-mMjoS45kXSHSm0ZAQ1whQZvBWC_CVx80klTf-TsnAQ8eo-74NuJpGANVJjSkroBkOh3k5mZZG-nNFUSzO2-sHPrPk7TGXbp7u_eCVd_B-r2hYhX_odVHJvwvNUobFhLpjMVaU4qkZ--qEfRX0Z2r4AozmrPsEUR3DazgzVw_iE_OthzgFdnPYwaJQFd9PhNA7iz64SaL4tS8" \
 https://<server>/mobile/api/com.magnet.server/user/all

    • Sample Response

      [
{
  "userIdentifier": "ff80818150bfea110150c04b20a6001f",
  "clientId": "4724a19b-0add-418c-a42a-c982ba936af5",
  "firstName": "User1",
  "lastName": "Last1",
  "email": "[email protected]",
  "userName": "user1",
  "password": "n/a",
  "userRealm": "DB",
  "roles": [
    "USER"
  ],
  "otpCode": "n/a",
  "userAccountData": {}
}
]

  2. Search Users:

    • Path

      GET https://<server>/mobile/api/com.magnet.server/user/query?q=<property>:<value>

    • Sample Request

      curl -X GET \
 -H "Authorization: Bearer BdnmKoeKRY33fhSIW0lUG8Kz7jUdluEsvkff0SaPGL6w0LYRhV9CyGehPOt3caEXJh69C3257lPYbh_YnpRwy36DHt74PkC-mMjoS45kXSHSm0ZAQ1whQZvBWC_CVx80klTf-TsnAQ8eo-74NuJpGANVJjSkroBkOh3k5mZZG-nNFUSzO2-sHPrPk7TGXbp7u_eCVd_B-r2hYhX_odVHJvwvNUobFhLpjMVaU4qkZ--qEfRX0Z2r4AozmrPsEUR3DazgzVw_iE_OthzgFdnPYwaJQFd9PhNA7iz64SaL4tS8" \
 https://<server>/mobile/api/com.magnet.server/user/query?q=userName:user1*

    • Sample Response

      [
{
  "userIdentifier": "ff80818150bfea110150c04b20a6001f",
  "clientId": "4724a19b-0add-418c-a42a-c982ba936af5",
  "firstName": "User1",
  "lastName": "Last1",
  "email": "[email protected]",
  "userName": "user1",
  "password": "n/a",
  "userRealm": "DB",
  "roles": [
    "USER"
  ],
  "otpCode": "n/a",
  "userAccountData": {}
}
]

    • Parameters

      The user discovery uses Elasticsearch URI search conventions to filter, sort, and paginate results.

      property the property name you would like to search within. Acceptable values are `userName`, `firstName`, `lastName`, `email`, `userRealm`, `userStatus`, `userIdentifier`.
      value The search query. Enclose within asterisk(*) to return wildcard matches.