Get started

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”):

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

Entity types and attributes

Access schemas

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:

• /entity
• /entity.delete
• /entity.replace
• /entity.update

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.

📘

In order to authorize a direct edit (e.g. /entity.update) call with the access token, you must add a write_with_token access schema to your login client. Include all data attributes in the access schema that you plan to edit via /entity call. See Create an access schema.

We should also point out that janrain-oauth authentication is a modified form of OAuth authentication. It’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. Example cURL command:

curl --location 'https://se-demos-gstemp.us-dev.janraincapture.com/entity' \
  --header 'Authorization: OAuth 298jcvnxkawx454r5'

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.

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=