janrain-signed
Our Registration API supports a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. Using this helps to protect against replay attacks, and ensures that client secrets are well protected.
APID Authorization Headers
Example Request
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=
Signature
To generate the signature you will need the following:
- The root-anchored API endpoint (for example /entity.find).
- The parameters of the API call as key=value pairs, sorted alphabetically and separated by newlines (\n).
- The date as specified in the Date header in your request.
- Your client secret.
- Your client Id.
To generate the signature:
- Concatenate the endpoint, datetime, and sorted parameters with newline characters ('\n'). This creates the string that we will sign.
- Use the client_secret to sign the string using SHA-1, then base64 encode the result.
- Prepend your client Id to this signature with a colon (:).
The resulting string is a signature that uniquely identifies a single request.
Below we have included a python implementation of the signed header request for further clarity and convenience:
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)}
For code examples in other languages, take a look at our sample code repo.
Authorization string
Used to send the authorization signature.
Example:
basic-auth
The Entity and Entity Types API supports basic HTTP authentication using owner credentials. To create the authorization code, combine your client ID and secret like this: client Id + ":" + secret. And then base64 encode the result.
Owner credentials give you full control over all the entity and entity type endpoints. If you all you need is read-only access to the user profile (entity) endpoints, you can use a direct_read_access client. If you need full control over the entity endpoints but you don't need access to the entity type endpoints, you can use a direct_read_access client.
Authorization string
Used to send the authorization code.
Example:
janrain-oauth
Some of our Registration API endpoints support a custom variant of OAuth using access tokens. The following endpoints accept OAuth acccess token authentication:
- /entity
- /entity.delete
- /entity.replace
- /entity.update
- /entityType
Authorization string
Used to send the access token.
Example: