The Entity and Entity Type API operations support three different methods of authentication, with most organizations opting to to use basic authentication. (The other two authentication options, janrain-signed and janrain-oauth, are also detailed in this article.) To employ basic authentication authentication, use the client ID of an API client as your username and the client secret of that API client as the password. Both the client ID and client secret can be found in the Manage Properties section of Console (in Console, API clients are referred to as “properties”):

imgimg

Note that you must use an API call that has the required permissions when making your operation. Typically this means a client assigned the owner feature. See the API client permissions section of this document for more information.

Create a basic authentication string

To create an authentication string, combine your API client ID, a colon (:), and your client secret into a single value. For example, if your client ID is abcdefg and your client secret is hijklmnop, that value would look like this:

abcdefg:hijklmnop

Next, take this string and base64 encode it. On a Mac, you can encode the string using this command:

echo -n "abcdefg:hijklmnop" | base64

If you’re running Microsoft Windows, you can encode the string by using a Windows PowerShell command similar to this:

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("abcdefg:hijklmn"))

The resulting value (e.g., YWJjZGVmZzpoaWprbG1ub3A) can then used in your authentication header.

If you're making API calls using Postman, select Basic Auth as your identification type, then use the client ID as the username and the client secret as the password. In that case, you won't have to combine the strings and then base64 the combined value. That's because Postman does this for you.

API client permissions

Entities and user profiles

Endpointowneraccess_ issuerdirect_ accessdirect_read _accesslogin_client
View a User Profile
POST
Search for User Profiles
POST
Count User Profiles
POST
Modify a User Profile
POST
Replace User Profile
POST
Create a User Profile
POST
Create Multiple User Profiles
POST
Invalidate a User Session
POST
Delete a User Profile
POST

Entity types and attributes

Endpointowneraccess_ issuerdirect_ accessdirect_read _accesslogin_client
List Entity Types
POST
View an Entity Type
POST
Create an Entity Type
POST
Create an Attribute
POST
Delete an Attribute
POST
Create a Validation Rule
POST
List Your Validation Rules
POST
Delete a Validation Rule
POST

Access schemas

Endpointowneraccess_ issuerdirect_ accessdirect_read _accesslogin_client
List Access Schemas
POST
Create an Access Schema
POST
Assign Constraints to an Attribute
POST
Delete an Access Schema
POST

janrain-oauth authentication

The proprietary janrain-oauth authentication method enables you to employ an access token and a modified form of OAuth authentication to call the following API endpoints:

Keep in mind that you can only manage the user profile assigned to the access token. (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 member or the key_value member and try returning information for someone other than Karim Nafir. Will you be able to view the user profile for that user? No. Instead, the /entity operation ignores the uuid parameter and the key_value member and any other members that let you target a user account. You can enter a different UUID or a different email address if you want, but those members are ignored and you’ll only get back information for Karim Nafir:

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

In other words. you can only view, and can only modify or delete, the user profile assigned to the access token.

📘

With janrain-oauth authentication your operation ignores any members that target a specific user (parameters like uuid and key_value). However, your operation does respect members 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 back, but you can't change the user profile the information is retrieved from.

We should also point out that janrain-oauth authentication is a modified form of OAuth authentication. I’s not the same sort of OAuth authentication used by Hosted Login. For example, a Hosted Login access token can’t be used to call any of the /entity endpoints. Such a call results in an error.

Instead, access tokens used by the Entity and Entity Type API operations must be obtained by using the Authentication API . 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 be used to call one of the /entity endpoints. For example, if you’re using Postman, set the authentication type to OAuth 2.0 and then configure the Current Token properties like this:

imgimg

In other words:

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

At that point you call the operation. In fact, you can even make that call without setting any other parameters. You don't need to include a user UUID or an entity type. Instead, that information is derived from the access token.

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

A Curl command for returning this same information looks similar to this:

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

janrain-signed authentication

You can also use janrain-signed, a custom HTTP authentication scheme based on a keyed-HMAC (Hash Message Authentication Code), when calling the Entity and Entity Type APIs. Using this approach helps to protect against replay attacks and ensures that client secrets are well protected. Here’s what an API call might look like when using janrain-signed:

GET /entity.find?type_name=user&filter=lastUpdated >= '2016-01-01'HTTP/1.1
  Host:training-pse.janraincapture.com
  Date: 2016-02-2619:08:44
  Authorization:Signature apkrahlfumwse2e9nvrrotv6vchuptzw:rRSudiGtMM5hEHYcwP49kt18jNk=

To generate the signature you need to complete the following procedure:

  1. Concatenate the endpoint, datetime, and sorted parameters with newline characters (\n). This creates the string to be signed.
  2. Use the client secret to sign the string using SHA-1, then base64 encode the result.
  3. Prepend your client Id to this signature with a colon (:).

The resulting string uniquely identifies a single request.

For example, the following Python code creates a signature:

importhmac
frombase64 importb64encode
fromhashlib importsha1
defmake_signed_auth_header(endpoint, params, datetime, client_id, secret):
    kv_params = ['{}={}'.format(k, v) fork, v inparams.items()]
    kv_params.sort()
    kv_string = '\n'.join(kv_params)
    str_to_sign = '{}\n{}\n{}\n'.format(endpoint, datetime, kv_string)
    hashed_str = b64encode(hmac.new(secret, str_to_sign, sha1).digest())
    return{'Authorization': 'Signature {}:{}'.format(client_id, hashed_str)}

That code returns a value similar to this:

Authorization: Signature apkrahlfumwse2e9nvrrotv6vchuptzw:Pm0y2b8b/tH4HrEqKqSm7zQk1s8=