Managing User Profiles by Using janrain-oauth Authentication

User profiles are typically managed by using the Entity APIs and basic authentication, an approach that requires you to employ the client ID of an owner client (or a direct access client) as the API call's username and the client secret of that client as the API call's password.

However, there’s another form of authentication that can be used to manage user profiles; this alternate method (janrain-oauth) allows you to employ an access token and a modified form of OAuth authentication to call the following API endpoints: 

Before you get too carried away by all this, keep in mind that there is one caveat here: you can only manage the user profile associated with the access token. (As compared to basic authentication, where you can manage any user profile.) For example, suppose you obtain an access token for Karim Nafir. If you use that token to call the entity endpoint, you’ll get back information for Karim Nafir:

{
    "result": {
        "givenName": "Karim",
        "familyName": "Nafir",
        "displayName": "Karim Nafir"
    },
    "stat": "ok"
}

No surprise there. However. suppose you change the value of the uuid parameter or the key_value parameter and try returning information for someone other than Karim Nafir. Will you be able to view the user profile for that user? In a word: no. Instead, the entity endpoint ignores the uuid parameter and the key_value parameter and any other parameters that let you target a different user account. You can enter a different UUID or a different email address if you want, but those parameters will be ignored and you’ll only get back information for Karim Nafir:

{
    "result": {
        "givenName": "Karim",
        "familyName": "Nafir",
        "displayName": "Karim Nafir"
    },
    "stat": "ok"
}

Like we said, you can only view, and can only modify or delete, the user profile associated with the access token.

Period.

Note. As noted, with janrain-oauth authentication your API call ignores any parameters used to target a specific user (parameters like uuid and key_value). However, your API call will respect parameters such as attributes, which lets you specify the set of attributes and attribute values to be returned by the call. In other words, you can customize the information you get bacj, but you can't change the user profile that the information is derived from: if you have an access token from User A you can only get back information from User A's profile. To view the user profile for User B you'll need to get a separate access token for User B.

We should also point out that this is a modified form of OAuth authentication: it’s not the same sort of authentication used by Hosted Login. In fact, a Hosted Login access token can’t be used to call any of the entity endpoints; an API call that tries that simply results in an error similar to this one:

{
    "error": "invalid_argument",
    "request_id": "84v3keepgwv4pj8x",
    "error_description": "malformed access token",
    "stat": "error",
    "code": 200,
    "argument_name": "access_token"
}

Instead, access tokens used by the Entity API endpoints must be obtained by using the Authentication APIs. For example, here’s a Curl command that returns an access token for the user with the UUID 3c388dd9-5bcc-4883-9a91-d51129110a4a:

curl -L -X POST \
  'https://se-demos-gstemp.us-dev.janraincapture.com/access/getAccessToken' \
  -H 'Authorization: Basic YjZ1amFla3Fmc2dyM2RlZjdtemJuODU5ZTU2aHNncHI6Mzd2YzRqbXEyZ3VlcDdmdDhzcHRud3VwY2hjdHI0OWE=' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type_name=GREG_DEMO' \
  --data-urlencode 'uuid=3c388dd9-5bcc-4883-9a91-d51129110a4a'

The API response, and the accompanying access token, will look similar to the following

{
    "accessToken": "298jcvnxkawx454r5",
    "stat": "ok"
}

That access token (298jcvnxkawx454r5) can then be used to call one of the entity endpoints. For example, if you’re using Postman to make your API call, set the authentication type to OAuth 2.0 and then configure the Current Token properties like this:

In other words:

  1. Select Available Tokens from the Access Token dropdown.
  2. Paste the access token itself intio the unlabeled field beneath the dropdown.
  3. Select Bearer from the Header Prefix dropdown. 

At that point, you can make your API call; in fact, you can even make that call without setting any other parameters (e.g., you don't need to include a user UUID or an entity type: that information is derived from the access token):

Without any other parameters, the preceding command returns all the attributes and attribute values for the user profile associated with the access token.

And since you asked, a Curl command for returning this same information will look similar to this:

curl -L -X POST \
  'https://se-demos-gstemp.us-dev.janraincapture.com/entity?access_token=26ccvnxxuwx45m7g'

It really is that easy.

It's equally easy to modify or delete a user profile. For example, here’s a Postman command that changes a user’s city of residence. Note that: 1) there’s no identifying information here other than the access token; and, 2) we used no parameters other than attribute_name and value (which we need to specify the attribute being changed and the new value being assigned):

The corresponding Curl command looks like this:

curl -L -X POST \
  'https://se-demos-gstemp.us-dev.janraincapture.com/entity.update?access_token=yp4p2swzjzpngph2' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'attribute_name=primaryAddress' \
  --data-urlencode 'value={"city": "Portland"}'