Janrain Client API Documentation

Client Endpoints Overview

Clients Endpoints

The /clients/* endpoints are used for creating, deleting and editing Registration clients. A client has access to the API (and, if applicable) the UI. Default clients have no permissions, so you need to configure them in the Janrain Dashboard unless you add permissions using the features parameter. The client_id and client_secret are generated by Janrain and included in the API response. A /clients/* call may only be made by the owner client, denoted by the Owner icon in the Dashboard. These endpoints are also used to reset client secrets.

Settings Endpoints

The /settings/* endpoints are used to make changes to your Registration Dashboard settings. You can change your own settings or use the from_client_id parameter to change another user's settings. You need to have owner permission to make changes to any account that is not your own. See individual endpoints for call examples and different use cases.

Security Schemes

x-janrain-hmac-authorization 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-26 19: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:

  1. Concatenate the endpoint, datetime, and sorted parameters with newline characters ('\n'). This creates the string that we will sign.
  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 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:

import hmac
from base64 import b64encode
from hashlib import sha1


def make_signed_auth_header(endpoint, params, datetime, client_id, secret):
    kv_params = ['{}={}'.format(k, v) for k, v in params.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: Authorization: Signature apkrahlfumwse2e9nvrrotv6vchuptzw:Pm0y2b8b/tH4HrEqKqSm7zQk1s8=

Responses

Basic Authentication basic

Our Registration API supports basic HTTP authentication using your application owner credentials. To create the authorization code, combine your client ID and secret like this client_id + ":" + secret, then base64 encode the result. Most RESTful frameworks support basic authentication natively.

Authorization string

Used to send the authorization code.

Example: Authorization: Basic aW1fYV9saXR0bGVfdGVhX3BvdF9zaG9ydF9hbmRfc3Q6b3V0X2hlcmVfaXNfbXlfaGFuZGxlX2hlcmVfaXNfbXk=

Responses

x-janrain-oauth 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:

For more information for this method of authentication, refer to the Use OAuth Authentication topic.

Authorization string

Used to send the access token.

Example: Authorization: OAuth SlAV32hkKG

Responses

Endpoints

https://{app}.janraincapture.com

URI Parameters

app string required

The name of the app domain.

Example: your-app-domain

/clients/add

Description

Add a new client to Registration. Once created, your new client will have access to the API, and if applicable, the UI. Default clients have no permissions, so you need to configure them in the dashboard, unless you add permissions using the features parameter.

The client_id and client_secret are generated by Janrain and included in the API response. This API call may only be made by the owner client, denoted by the ‘owner’ icon in the Janrain dashboard.

Optionally, you may set the features for the client at the time of creation. The features that you can add are:

  • owner — Complete admin access.
  • access_issuer — Can issue access tokens for other clients.
  • direct_read_access — Has read access to all records.
  • direct_access — Has read and write access to all records.
  • login_client — This client has permission to use login and registration-based API endpoints.

For more information on these features, see the Create an API Client topic.

post

Description

Example Request

Adds a client with the description "Client with direct access" and gives that client the "direct_access" feature.

curl -X POST \
-H "Authorization: Basic aW1fYV...NfbXk=" \
--data-urlencode description='Client with direct read access' \
--data-urlencode features='["direct_read_access"]' \
https://my-app.janraincapture.com/clients/add

Authorized Clients

owner

Security

Query Parameters

description string required

A string description of the client.

features string

A JSON array of feature names that the client has; defaults to the empty list.

Responses

200 OK

Example Error Response

{
  "argument_name": "features",
  "request_id": "b83954jrg5hmc9kr",
  "code": 200,
  "error_description": "features was not valid for the following reason: superuser_owner is not a valid feature name",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "features": [
    "direct_read_access"
  ],
  "description": "\"Client with direct read access\"",
  "client_id": "12345abcde12345abcde",
  "client_secret": "edcba54321edcba54321",
  "stat": "ok"
}

/clients/clear_whitelist

Description

Clears the IP whitelist for a target client, resetting it to the default value that allows all IP addresses. Only the owner client may make this API call. The default whitelist is ["0.0.0.0/0"] (all IP addresses are allowed).

post

Description

Example Request

Clears the whitelist for a client with the ID value 67890fghij67890fghij.

curl -X POST \
-H "Authorization: Basic aW1fYV...NfbXk=" \
--data-urlencode for_client_id=67890fghij67890fghij \
https://my-app.janraincapture.com/clients/clear_whitelist

Authorized Clients

owner

Security

Query Parameters

for_client_id string

The ID for the client whose whitelist will be cleared. If you don’t use this parameter, the whitelist will be cleared for the owner client.

Responses

200 OK

Example Error Response

{
  "argument_name": "for_client_id",
  "request_id": "ytjjh5pqjhkwyhdr",
  "code": 200,
  "error_description": "for_client_id was not valid for the following
    reason: for_client_id is not a valid id",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "stat": "ok"
}

/clients/delete

Description

Deletes a client. Only the owner client may make this API call.

post

Description

Example

Delete a Capture client with the ID value 67890fghij67890fghij.

curl -X POST \
-H "Authorization: Basic aW1fYV...NfbXk=" \
--data-urlencode client_id_for_deletion=67890fghij67890fghij \
https://my-app.janraincapture.com/clients/delete

Authorized Clients

owner

Security

Query Parameters

client_id_for_deletion string required

The ID of the client to delete.

Responses

200 OK

Example Error Response

{
  "argument_name": "client_id_for_deletion",
  "request_id": "cepqfrsvtyqmyxf8",
  "code": 200,
  "error_description": "client_id_for_deletion was not valid for the
    following reason: client_id_for_deletion is not a valid id",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "stat": "ok"
}

/clients/list

Description

Get a list of the clients in your application, optionally filtered by client feature. Only the owner client can make this API call.

get

Description

Example

Get a list of clients with the features "direct_access" and "access_issuer".

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode has_features='["direct_access", "access_issuer"]' \
    https://my-app.janraincapture.com/clients/list

Authorized Clients

owner

Security

Query Parameters

has_features string

A JSON array features names; only clients which have at least one of the features in the array will be displayed. Valid values are: owner, access_issuer, direct_read_access, and direct_access.

Responses

200 OK

Example Error Response

{
  "argument_name": "has_features",
  "request_id": "n7uudpznfbrs79gu",
  "code": 200,
  "error_description": "has_features was not valid for the following reason: the JSON is not syntactically valid",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "results": [
    {
      "whitelist": [
        "0.0.0.0/0"
      ],
      "features": [
        "access_issuer",
        "direct_access",
        "owner"
      ],
      "description": "application owner",
      "client_id": "12345abcde12345abcde",
      "client_secret": "edcba54321edcba54321"
    }
  ],
  "stat": "ok"
}

/clients/reset_secret

Description

Generates a new client secret for a specified client ID. The old client secret will be valid for a specified grace period.

If you have a security issue, you can use this endpoint to change a client's client_secret value instead of generating a new client/secret pair (which would involve changing permissions, access schemas, and hard-coded instances of the credentials).

A configurable grace period for the old client_secret value is provided to allow changeover before the new secret breaks existing code.

post

Description

Example Request

Generate a new client secret for the client with ID 67890fghij67890fghij. The old client secret will remain valid for 24 hours.

curl -X POST \
-H "Authorization: Basic aW1fYV...NfbXk=" \
--data-urlencode for_client_id=67890fghij67890fghij \
--data-urlencode hours_to_live=24 \
https://my-app.janraincapture.com/clients/reset_secret

Authorized Clients

owner

Security

Query Parameters

for_client_id string required

The client_id for the client whose secret will be reset.

hours_to_live string required

An integer between 0 and 168 that determines how many hours the old client secret will be valid.

Responses

200 OK

Responses Fields

Field Type Description
new_secret dictionary The new client_secret value replacing the current client_secret.

Example Error Response

Triggered when a request of 320 hours was set with the hours_to_live parameter.

{
  "argument_name": "hours_to_live",
  "request_id": "zxu4ay2wfg8fb5ud",
  "code": 200,
  "error_description": "hours_to_live was not valid for the following
    reason: hours_to_live must be between 0 and 168",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "new_secret": "abcde12345abcde12345abcde12345",
  "stat": "ok"
}

/clients/set_description

Description

Change the description of a client. This can also be thought of as the name of the client.

This API call may only be made by the owner client.

post

Description

Example Request

Change the description of the client with the ID "67890fghij67890fghij" to "New client description".

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=67890fghij67890fghij \
    --data-urlencode description='New client description' \
    https://my-app.janraincapture.com/clients/set_description

Authorized Clients

owner

Security

Query Parameters

for_client_id string

The client ID of the client whose description is being changed. If this parameter is not used, the description of the application owner will be changed.

description string required

The new description of the target client.

Responses

200 OK

Example Error Response

{
  "argument_name": "for_client_id",
  "request_id": "73et727cxds4vwtx",
  "code": 200,
  "error_description": "for_client_id was not valid for the following
    reason: for_client_id is not a valid id",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "stat": "ok"
}

/clients/set_features

Description

Change the features that a target client has by overwriting the old feature list. This API call may only be made by the client's owner. The owner client may not remove the owner feature from itself.

Note: You may assign more that one owner client.

post

Description

Example Request

Overwrite the old features list for the client with ID value 67890fghij67890fghij with a list consisting of the single value owner.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=67890fghij67890fghij \
    --data-urlencode features='["owner"]' \
    https://my-app.janraincapture.com/clients/set_features

Authorized Clients

owner

Security

Query Parameters

for_client_id string

The ID for the client whose features you wish to set. If this parameter is not used, the features are set for the client's owner.

features string required

A JSON array of feature values to assign to the client. The available values are:

  • owner — Complete admin access.
  • access_issuer — Can issue access tokens for other clients.
  • direct_read_access — Has read access to all records.
  • direct_access — Has read and write access to all records.
  • login_client — Creates a read-only client for logging users into your website or application. This prevents malicious users from gaining access to your owner client ID. See API Clients and Permissions for more details.

Note: Clients with the direct_read_access and direct_access features are still subject to the access schemas. For example, if a client has a write access schema defined, the client can write to the “foo” attribute only if it exists in the access schema and the client has the direct_access feature.

Note: The direct_access feature implies the direct_read_access feature.

Responses

200 OK

Example Error Response

{
  "argument_name": "features",
  "request_id": "at86pruhzayqxapr",
  "code": 200,
  "error_description": "features was not valid for the following reason:
    ninja_superuser is not a valid feature name",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "stat": "ok"
}

/clients/set_whitelist

Description

Change the IP whitelist for a target client, overwriting the previous whitelist. Only the client with the owner feature may make this API call. If the owner client sets the whitelist for itself, the whitelist must allow access from the IP address making the call. All new clients begin with a default whitelist of ["0.0.0.0/0"] (meaning that all IP addresses are allowed).

post

Description

Example Request

Change the IP whitelist for the client with the ID value 67890fghij67890fghij to an array that includes the IP address 123.4.5.6/7890.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=67890fghij67890fghij \
    --data-urlencode whitelist='["123.4.5.6/7890"]' \
    https://my-app.janraincapture.com/clients/set_whitelist

Authorized Clients

owner

Security

Query Parameters

for_client_id string

The ID for the client to which you want to apply the whitelist. If this parameter is not used, the owner client's whitelist is overwritten.

whitelist string required

A JSON array of CIDR addresses that constitutes the new whitelist for the client. Each value uses the format x.x.x.x/x.

Responses

200 OK

Example Error Response

{
  "argument_name": "whitelist",
  "request_id": "g8snkpqubwkd7kzh",
  "code": 200,
  "error_description": "whitelist was not valid for the following
    reason: invalid cidr address: 123.4.5.6/7890; value after slash
    must be 32 or less",
  "error": "invalid_argument",
  "stat": "error"
}
Response Example (application/json)
{
  "stat": "ok"
}

/settings/delete

Description

Delete a key from the settings for a particular client. Returns a Boolean indicating whether the key existed. This does not modify the application-wide default value for a key.

post

Description

Example Request

Delete the key owner for a particular client.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode key=owner \
    https://my-app.janraincapture.com/settings/delete

Authorized Clients

owner login_client direct_read_access direct_access access_issuer

Security

Query Parameters

key string required

The key to delete from the client settings. To find out the values available, use the settings/keys API call first.

for_client_id string

The client identifier whose key will be deleted. Note, only the application owner is authorized to send requests with this parameter.

Responses

200 OK

Response Example (application/json)
{
  "result": true,
  "stat": "ok"
}

/settings/delete_default

Description

Delete a key from the application-wide default settings. Returns a Boolean indicating whether the key existed. This does not modify any per-client settings.

post

Description

Example Request

Delete the default value of the key foo, which does not currently have a default value assigned.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode key=foo \
    https://my-app.janraincapture.com/settings/delete_default

Authorized Clients

owner

Security

Query Parameters

key string required

The key to delete from the application settings. To find out the values available, use the settings/keys API call first.

Responses

200 OK

Response Example (application/json)
{
  "result": false,
  "stat": "ok"
}

/settings/get

Description

Get the value associated with a key for a particular client_id. If the key has no value for that client, then the application-wide default value for that key is returned. If the key has no application default value, then null is returned.

get

Description

Example Request

Get the value of the key owner for a particular client.

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode key=owner \
    https://my-app.janraincapture.com/settings/get

Authorized Clients

owner login_client direct_read_access direct_access access_issuer

Security

Query Parameters

key string required

The key whose value you want to retrieve. To find out the values available, use the settings/keys API call first.

for_client_id string

The client identifier. Note, only the application owner is authorized to send requests with this parameter.

Responses

200 OK

Response Example (application/json)
{
  "result": "Jay",
  "stat": "ok"
}

/settings/get_default

Description

Get the application-wide default value of a key. Returns the value of the key or null if no such key exists.

get

Description

Example Request

Get the value of owner, which does not have a default value.

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode key=owner \
    https://my-app.janraincapture.com/settings/get_default

Authorized Clients

owner

Security

Query Parameters

key string required

The key whose value you want to retrieve. To find out the values available, use the settings/keys API call first.

Responses

200 OK

Response Example (application/json)
{
  "result": "null",
  "stat": "ok"
}

/settings/get_multi

Description

Look up multiple keys. Each value is retrieved, as in the settings/get command, by first looking at the client-specific setting, and then falling back to the application default setting.

get

Description

Example Request

Fetch the values of owner, level, and public for a specific client, where public has no client-specific value and no default value.

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode keys='["owner","public","level"]' \
    https://my-app.janraincapture.com/settings/get_multi

Authorized Clients

owner login_client direct_read_access direct_access access_issuer

Security

Query Parameters

keys string required

A JSON array of the keys to retrieve.

for_client_id string required

The client identifier whose keys will be retrieved. Note, only the application owner is authorized to send requests with this parameter.

Responses

200 OK

Response Example (application/json)
{
  "result": {
    "public": "true",
    "owner": "Jay",
    "level": "10"
  },
  "stat": "ok"
}

/settings/items

Description

Get all settings for a particular client, including those from the application-wide default settings. If a key is defined in both the client and application settings, only the client-specific value is returned. Returns a JSON object of all key-value pairs.

get

Description

Example Request

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    https://my-app.janraincapture.com/settings/items

Authorized Clients

owner login_client direct_read_access direct_access access_issuer

Security

Query Parameters

for_client_id string

The client identifier whose settings will be retrieved. Note, only the application owner is authorized to send requests with this parameter.

Responses

200 OK

Response Example (application/json)
{
  "result": {
    "owner": "Jay",
    "public": "true",
    "level": "10"
  },
  "stat": "ok"
}

/settings/keys

Description

Get all keys for a particular client, including those from the application-wide default settings. Returns an array of the keys.

get

Description

Example Request

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    https://my-app.janraincapture.com/settings/keys

Authorized Clients

owner login_client direct_read_access direct_access access_issuer

Security

Query Parameters

for_client_id string

The client identifer whose keys will be retrieved. Note, only the application owner is authorized to send requests with this parameter.

Responses

200 OK

Response Example (application/json)
{
  "result": [
    "level",
    "owner",
    "public"
  ],
  "stat": "ok"
}

/settings/set

Description

Assign a key-value pair for a particular client_id. If the key does not exist, it will be created. If the key already exists, this call overwrites the existing value.

Returns a Boolean that indicates whether the key already existed. true indicates the key has been overwritten. false indicates that a new key has been created.

Note: You cannot use settings/set to modify the application-wide default settings. You must use settings/set_default for this purpose.

post

Description

Example Request

Assign the value Robert to the key owner for the client with the ID fghi7890fghi7890.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode key=owner \
    --data-urlencode value=Robert \
    https://my-app.janraincapture.com/settings/set

Authorized Clients

owner login_client direct_read_access direct_access access_issuer

Security

Query Parameters

key string required

The key to add or modify.

value string required

The value to assign to the key.

for_client_id string

The client identifier whose setting will be modified. Note, only the application owner is authorized to send requests with this parameter.

Responses

200 OK

Response Example (application/json)
{
  "result": false,
  "stat": "ok"
}

/settings/set_default

Description

Set a key in the application-wide default settings. This will create a new key with a default value if the key does not yet exist in the application. If the key does exist, the value will be overwritten.

Returns a Boolean that indicates whether the key already existed. true indicates that the key has been overwritten, whereas false indicates that a new key has been created.

Note: You cannot use settings/set_default to modify any client-specific settings.

post

Description

Example Request

Assign the value default to the key permissions.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode key=permissions \
    --data-urlencode value=default \
    https://my-app.janraincapture.com/settings/set_default

Authorized Clients

owner

Security

Query Parameters

key string required

The key to add or modify.

value string required

The value to assign to the key.

Responses

200 OK

Response Example (application/json)
{
  "result": false,
  "stat": "ok"
}

/settings/set_default_multi

Description

Assign multiple keys in the application-wide default settings. This will create a new key with a default value if the key does not yet exist in the application. If the key does exist, the value will be overwritten.

Returns a Boolean value that indicates whether the key already existed. A true value means the key has been overwritten, whereas false means a new key has been created.

Note: You cannot use settings/set_default_multi to modify any client-specific settings.

post

Description

Example Request

Assigns the value Jay to the owner key, value true to the public key, and value 10 to the level key.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode items='{"owner":"Jay","public":"true","level":"10"}' \
    https://my-app.janraincapture.com/settings/set_default_multi

Authorized Clients

owner

Security

Query Parameters

items string required

A JSON object containing the key-value pairs to set for the client identifier.

Responses

200 OK

Response Example (application/json)
{
  "result": {
    "public": false,
    "owner": false,
    "level": false
  },
  "stat": "ok"
}

/settings/set_multi

Description

Assign multiple settings for a particular client_id. Returns a JSON object in which each key is mapped to a Boolean that indicates whether the key already existed. true indicates that a previous key did exist and has been overwritten, whereas false indicates that there was no previous key and a new key has been created. All values for the items parameter must be passed as strings inside quotations. Does not modify application-wide settings.

post

Description

Example Request

Assigns the value Jay to the owner key, value true to the public key, and value 10 to the level key.

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode items='{"owner":"Jay","public":"true","level":"10"}' \
    https://my-app.janraincapture.com/settings/set_multi

Authorized Clients

owner login_client direct_read_access direct_access access_issuer

Security

Query Parameters

items string required

A JSON object containing the key-value pairs to set for the client identifier.

for_client_id string required

The client identifier whose settings will be modified. Note, only the application owner is authorized to send requests with this parameter.

Responses

200 OK

Response Example (application/json)
{
  "result": {
    "owner": true,
    "public": false,
    "level": false
  },
  "stat": "ok"
}