/config/{app_id}/clients/{client_id}/settings

API clients serve two major purposes: they make authenticated requests against the Janrain REST APIs, and they (or, more specifically, API clients that have the login_client feature set) authenticate users during logon. Each client also has a collection of settings that help govern activities under the client's control. For example, the login_attempts setting specifies how many times a user can attempt to log on before his or her account is temporarily locked out.

The settings associated with an API client can be found in the Capture Dashboard under the Settings tab:

The /config/{app_id}/clients/{client_id}/settings endpoint enables you to return settings information for a specific API client. In addition, the PUT method enables you to modify client settings.

This endpoint includes the following methods:


GET

Description

Returns the settings associated with a specific API client. The endpoint returns the following information for the specified client:

  • Janrain client settings configured specifically for the client itself.
     
  • Janrain settings configured at the global level. As a general rule, global settings apply to all API clients. However, if the client has its own version of the setting the client version applies. For example, suppose the global settings show this:

    login_attempts = 7

    Let’s further suppose that the API client includes this setting

    login_attempts = 4

    In this case, anyone logging on using the API client will get a maximum of 4 logon attempts before their logon privileges are temporarily suspended. This is because the API client setting (a local setting) overrides the global setting.

    Note, however, that there are some settings which can only be configured at the global level. For example, you can configure {entity_type}_distinguisher_field at the individual client level; however, that setting will be ignored. That's because {entity_type}_distinguisher_field is only valid when configured at the global scope.
     
  • Custom settings defined for the client. Custom settings are defined as any setting not included in the Janrain client settings.

Client settings, global settings, and custom settings are returned as separate JSON objects.

To return settings information for a specified API client, your API call must run with either owner credentials or with the API credentials of the client in question.  

Authentication

This endpoint supports Basic authentication. 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 the string and base64 encode it.

For example, on a Mac, you can base 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=) should be used in your authentication header.

If you are 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.

Make sure that your API client has the all the permissions (for example, the right to read user profile information) needed to complete the API call.

Base URL

The base URL for this endpoint is your Janrain Configuration API domain followed by /config/ followed by your application ID. For example, if you are in the US region and your application ID is htb8fuhxnf8e38jrzub3c7pfrr, then your base URL would be:


https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr

Allowed regions are:

  • us 
  • eu 
  • au 
  • sa 
  • cn

Sample Request (curl)

This command returns settings information for the API client with the client ID xyv3q7xhces2yy7cumgrte24epx4m2st.


curl -X GET \
    https://v1.api.us.janrain.com/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu/settings

Running Code Samples Using Postman

The Janrain REST API code samples are written using Curl, but they can easily be run from within Postman. To use one of our code samples in Postman:

  1. Click the Copy to Clipboard button located directly beneath the code sample
  2. In Postman, click Import to display the Import dialog box.
  3. In the Import dialog box, click Paste Raw Text, and then paste in the copied code. The Import dialog box should look similar to this:

  4. Click Import, and the Curl command will be converted to a format that can be run from within Postman. All you need to do now is configure the command to work with your Janrain implementation.

Responses

200 OK

If your call to this endpoint succeeds, you'll get back settings information for the specified API client:


{
   "_global": {
       "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/settings",
       "cache_settings": 0,
       "custom": {
           "email_verification_url": "https://console-datateam.dev.or.janrain.com/#/verifyEmail",
       },
       "default_flow_name": "standard",
       "default_flow_version": "20170915215708415365",
       "email_method": "ses_sync",
       "email_sender_address": "\"Janrain Console\" ",
       "password_recover_url": "https://console-datateam.dev.or.janrain.com/#/passwordReset",
        "rpx_app_id": "kbcpdniaklcfajlapmif",
       "rpx_key": "69a70c57f856dcb7a28f672fc0c8e8556c1e3672",
       "rpx_realm": "capture",
       "site_name": "console-datateam.dev.or.janrain.com"
    },
   "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu/settings",
   "custom": {},
   "default_flow_name": "standard",
   "default_flow_version": "20170915215708415365",
   "email_method": "ses_sync",
   "email_sender_address": "\"Janrain Console\" ",
   "rpx_app_id": "kbcpdniaklcfajlapmif",
   "rpx_key": "69a70c57f856dcb7a28f672fc0c8e8556c1e3672",
   "rpx_realm": "capture",
   "site_name": "New Test Site"
}

@janrain.com>@janrain.com>

Error Codes

The following table includes information about some of the error codes that you could encounter when calling this endpoint.

Error Code

Description

401/403

Error Message: Authentication required.

You either failed to provide credentials or provided invalid credentials. This endpoint requires Basic authentication.

404

Error Message: Client ID not found.

Error Message: Application ID not found.

You did not provide a valid application and/or client ID.

If you encounter an error when calling this endpoint that error message will look similar to this:


{
   "errors": "Authentication required."
}     
                                                    


PUT

Modifies the client settings associated with a specific API client. This endpoint can be used to:

  • Add new client settings.
  • Modify existing client settings.
  • Delete existing client settings.

Before you begin working with this endpoint, you need to understand the "rules" for managing client settings:

  • You can only manage the settings associated with an individual API client; this endpoint cannot modify the global client settings. However, the endpoint can modify any global settings that are referenced in the individual client settings. For example, suppose you have login_­attempts in both the global settings and in the client settings for API Client A. You can use this endpoint to delete login_attempts from Client A. When you do so, however, the login_attempts setting in the global settings (or in the settings for Clients B, C, D, E, etc.) will not be deleted.
     
  • You must specify all the settings for a client in the response body of your API call. When you do so:
     
    • If the referenced setting does not exist, it will be added to the client. For example, suppose your API calls specifies that login_attempts should equal 7. If the login_attempts setting does not exist, it will be created and the value set to 7. If the setting already exists, then its value will be changed to 7.
       
    • Any settings currently associated with the client but not in the request body will be deleted. For example, suppose your client has the following three settings:

  • login_attempts
  • login_attempts_threshold
  • recover_code_lifetime

Let's further suppose that your request body updates the following two settings:

  • login_attempts
  • login_attempts_threshold

    When you run your command, login_attempts and login_attempts_threshold will be updated. However, recover_code_lifetime will be deleted. Why? Because it was not included in the request body.

Based on those rules, you might consider retrieving all the existing settings and values for a client before you modify any of those settings. For example, suppose you use the GET method to return the following settings and values for a client:


{
    "site_name": "Documentation Test Site",
    "login_attempts_threshold": "60",
    "login_attempts": "4",
    "recover_code_lifetime": "3600",
    "verification_code_lifetime": "3600",
    "_global": {
        "rpx_realm": "greg-stemp",
        "user_search_query_fields": "[\"created\", \"displayName\", \"email\", \"lastUpdated\", \"uuid\"]",
        "user_distinguisher_field": "primaryAddress.country",
        "test_search_allow_empty": "true",
        "rpx_key": "a999b571f79a416002b7ed4137375bffb60eb1a4",
        "user_search_allow_empty": "true",
        "email_method": "ses_sync",
    }
}

Copy the client-specific settings and paste them into the request body of your update call. Within the request body, make any necessary changes. For example, you might want to change the recover code and verification code lifetimes:


{
    "site_name": "Documentation Test Site",
    "login_attempts_threshold": "60",
    "login_attempts": "4",
    "recover_code_lifetime": "2400",
    "verification_code_lifetime": "2400",
}

Note that the first three settings – site_namelogin_attempts_threshold, and login_attempts– remain in the request body even though no changes are being made to them. Do not remove the settings from the request body. If you do, they will also be deleted from the API client settings.

Authentication

This endpoint supports Basic authentication. 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 the string and base64 encode it.

For example, on a Mac, you can base 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=) should be used in your authentication header.

If you are 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.

Make sure that your API client has the all the permissions (for example, the right to read user profile information) needed to complete the API call.

Base URL

The base URL for this endpoint is your Janrain Configuration API domain followed by /config/ followed by your application ID. For example, if you are in the US region and your application ID is htb8fuhxnf8e38jrzub3c7pfrr, then your base URL would be:


https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr

Allowed regions are:

  • us 
  • eu 
  • au 
  • sa 
  • cn

Sample Request (curl)

This command updates the site_name setting for the API client with the client ID xyv3q7xhces2yy7cumgrte24epx4m2st:


curl -X PUT \
  https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xyv3q7xhces2yy7cumgrte24epx4m2st/settings \
  -H 'Content-Type: application/json' \
  -d '{
   "site_name":"Documentation Test Site"
}
'

Running Code Samples Using Postman

The Janrain REST API code samples are written using Curl, but they can easily be run from within Postman. To use one of our code samples in Postman:

  1. Click the Copy to Clipboard button located directly beneath the code sample
  2. In Postman, click Import to display the Import dialog box.
  3. In the Import dialog box, click Paste Raw Text, and then paste in the copied code. The Import dialog box should look similar to this:

  4. Click Import, and the Curl command will be converted to a format that can be run from within Postman. All you need to do now is configure the command to work with your Janrain implementation.

Responses

200 OK

If your API call succeeds, you should get back the updated property values for the API client:


{
   "_global": {
       "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/settings",
       "custom": {
       }
    },
   "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu/settings",
   "custom": {},
   "default_flow_name": "standard",
   "default_flow_version": "20170915215708415365",
   "email_method": "ses_sync",
   "email_sender_address": "\"Janrain Console\" ",
   "rpx_app_id": "kbcpdniaklcfajlapmif",
   "rpx_key": "69a70c57f856dcb7a28f672fc0c8e8556c1e3672",
   "rpx_realm": "capture",
   "site_name": "Documentation Test Site"
}
@janrain.com>

Error Codes

The following table includes information about some of the error codes that you could encounter when calling this endpoint.

Error Code

Description

400

Error Message: <setting key> can only be configured as a global setting.

The specified key cannot be set at the individual client level; it can only be set at the global level.

400

Error Message: <setting key> is not a valid string

Typically, you tried to set the specified key to a string value that included blank spaces. Remove the blank spaces and try the API call again.

400

Error Message: <setting key> must be a boolean value.

The specified can only be set to true or false.

400

Error Message: <setting key> must be valid json.

The specified key must use the JSON syntax.

400

Error Message: <setting key> must be an integer.

The specified key only accepts integer values.

400

Error Message: Value is supplied that does not pass additional validation rules defined for the specified key.

Verify the validation rules for the specified key and then try your API call again.

401/403

Error Message: Authentication required.

You either failed to provide credentials or provided invalid credentials. This endpoint requires Basic authentication.

404

Error Message: Client ID not found.
Error Message: Application ID not found.

You did not provide a valid application and/or client ID.

If you encounter an error when calling this endpoint that error message will look similar to this:


{
   "errors": "Authentication required."
}