Use OAuth Authentication

Registration RESTful api calls normally use client credentials to authenticate with Janrain, allowing the API to complete the call.  This method uses the client_secret and client_id  as parameters in the call.

However, the entityentity.create, entity.update, entity.replace, and entity.delete API calls may alternatively use the OAuth authentication method. Using this method, the client_secret and client_id are exchanged for a code or a token. This token is then used as a parameter in the RESTful call.

Two Token Types

Warning: For security’s sake, never send the client secret over an unsecure connection or use it in a browser. There are exploits for gathering sensitive information via email, instant messaging, or even ticket tracking systems. Once the client secret is compromised, your user data is at risk.

How to use Oauth Authentication to retrieve an access_token

  1. Determine the redirect_uri for the token will be delivered. This path should lead to a page that has the ability to capture the token.
  2. Define the type_name, and use a record_selector to determine any entities that access will be granted to.
  3. Use these values to make an getAuthorizationCode call.
  4. The authorization code is then returned to the redirect_uri. Use this code to make an oauth/token call.
  5. The access_token is returned to the redirect_uri specified in the oauth/token call (Note: this may be different than the one used to retrieve the access_code.)

How to retrieve a creation_token

  1. Define the type_name, and the amount of time the token will be valid.
  2. Use these values to make an getCreationCode call.
  3. The authorization code is then returned directly by the call in the JSON response. Use this code to make an entity.create call without using the client_secret/client_id combo.

The following is an example of making an oauth/token API call using PHP and the cURL library:

def new_access_token(auth_code, redirect_uri)
  command = "oauth/token"
  args = {
    :code => auth_code,
    :redirect_uri => redirect_uri,
    :grant_type => 'authorization_code',
    :client_id => ENV['JANRAIN_CAPTURE_CLIENT_ID'],
    :client_secret => ENV['JANRAIN_CAPTURE_CLIENT_SECRET'] }

  if options['application_id']
    args['application_id'] = options['application_id']
  end

  json_data = capture_api_call(command, args)
  return json_data
end
// ----------
// Given an auth code, get a new access token and update the capture session
// in the PHP session variable 'capture_session'.  Also returns a PHP array of
// the capture session.
// Uses the global variables defined at the top of this file.

function new_access_token($auth_code, $redirect_uri)
{

  global $options;

  $command   = "oauth/token";
  $arg_array = array('code'          => $auth_code,
                     'redirect_uri'  => $redirect_uri,
                     'grant_type'    => 'authorization_code',
                     'client_id'     => $options['janrain.settings.capture.clientId'],
                     'client_secret' => $options['janrain.settings.capture.clientSecret']);

  if(isset($options['application_id'])) {
    $arg_array['application_id'] = $options['application_id'];
  }

  $json_data = capture_api_call($command, $arg_array);

  return $json_data;
}

?>