Get started

The Authentication API is split fairly-evenly between operations that require authentication and operations that don’t require authentication. The operations that don’t require authentication (at least in the sense of, say, Basic authentication) include the following:

• /oauth/auth_native
• /oauth/auth_native_traditional
• /oauth/forgot_password_native
• /oauth/link_account_native
• /oauth/register_native
• /oauth/register_native_traditional
• /oauth/unlink_account_native
• /oauth/update_profile_native
• /oauth/verify_email_native

Note that this doesn't mean that anyone can access and employ these operations any time they want. Although you don't employ a standard authentication method with these operations, your API operation does need:

• A valid access token. This token needs to be obtained by using the Authentication APIs. Access tokens obtained elsewhere (for example, by using Hosted Login) won't work.

• The client ID of an Identity Cloud login client. This must be the same login client used when acquiring the access token.

Some of the operations have additional security requirements besides an access token and client ID. For example, the /oauth/auth_native_traditional endpoint requires the email address and password of the user logging in.

The remaining Authentication endpoints support two different methods of authentication:

• basic authentication
• janrain-signed authentication.

To use basic authentication, configure 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 client that has the required permissions when making your API call. 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 a basic 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 the 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) is then referenced in your authentication header.

If you're making API calls using Postman, select Basic Auth as the identification type, then use the client ID as the username and the client secret as the password. In this case, you don't need to base64 encode the values and create an authentication string: Postman does that work for you.

API client permissions

The following tables lists the API client types (based on client features) and whether they can call the Authentication API operation. In order to call an operation, the client needs to include at least one of the features allowed to make the call (signified in the tables by a checkmark). See API clients and permissions for more information about client features.

Access tokens and codes

User profiles

Using janrain-signed authentication

If you don't want to use basic authentication, janrain-signed is a custom HTTP authentication scheme based on a keyed-HMAC (Hash Message Authentication Code) that can call the Authentication API. This approach helps 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 an authorization signature by using janrain-signed, complete the following procedure:

1. Concatenate the operation name, the date and time, and your operation members, separating individual members by using newline characters (\n). This creates the signature string.
2. Use the client secret of your API client to sign the string using SHA-1 and then base64 encode the result.
3. Prepend the client ID to your signature with a colon (:).

The resulting string can then used to uniquely identify a single request.

Here's sample Python code that creates a janrrain-signed 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=