/config/{appId}/settings

Returns the global settings for an application; in addition, you can also use the PUT method to modify any or all of those settings. By default, global settings apply to all the API clients in an application. For example, if the login_attempts setting is configured to 5, then all the API clients in the application will allow a user to make a maximum of 5 failed login attempts before temporarily locking the user out of the web site.

There is one exception, however. If the same setting is specifically defined for a client application, then client application setting takes precedence over the global setting. For example, suppose the global settings for login_attempts is 5 but, in Client A, login_attempts is set to 3. In that case, anyone using Client A will be limited to a maximum of 3 failed login attempts.

This endpoint includes the following methods:

GET

Description

Returns settings and values applied at the API client level; in the Console, these are the settings defined in the Manage Application section. This endpoint returns all the global settings as well as any custom settings configured at the global level. Your API call must have owner permissions in order to return the global settings.

URI Parameters

Parameter	Type	Required	Description
include_clients	string		Returns the global API client settings as well as any settings configured for each individual API client. If not included, this parameter is set to the default value (false). For example, suppose your global settings consist of just two values: login_attempts login_attempts_threshold If your API clients do not include any settings other than those two, then the endpoint returns only these two settings. However, suppose Client A includes an additional setting: site_name. In that case, the endpoint returns information about login_attempts, login_attempts_threshold, and site_name. The returned data consists of the global settings, plus any settings defined for an individual API client. (Note that the global settings are shown only once; they are not repeated for each client.)

Authentication

This endpoint supports Basic authentication.

How to Create an Authentication String

Base URL

The base URL for this endpoint is your 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:

Sample Request (curl)

This command returns settings information for the application with the ID 73jzx34tnr5ruhsze494ssgz2b.


curl -G \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg' \
  https://v1.api.us.janrain.com/config/73jzx34tnr5ruhsze494ssgz2b/settings

Running this command in Postman

Responses

200 OK

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


{
   "_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"
}

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: Application ID not found. You did not provide a valid application ID.

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: Application ID not found.

You did not provide a valid application ID.

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


{
   "errors": "Authentication required."
}

PUT

Description

Updates the global settings for an application. To specify the global settings, those settings must be put in the body parameter of your API call and must be formatted as a JSON value. For example:


{
     "custom": {
          "site_locale":"US"
     },
     "email_method": "ses_sync"
}

Two things to note here. First, you can configure custom settings for an application (custom settings are any settings not found on the API Client Settings page or returned by the /config/{appId}/settings/options endpoint). To define and configure custom settings, use the property name custom and then enclose the custom settings in a JSON object. For example, configure two custom properties application_region and is_test_site:


{
     "custom": {
          "application_region":"US",
         "is_test_site":"false"
     },
     "email_method": "ses_sync"
}

Any standard client settings (e.g., email_method) are individually defined after the custom property.

In addition to that, keep in mind that any global setting not defined in the body parameter will be deleted when you call the PUT method. For example, suppose your application includes the following two global settings:


"email_method": "ses_sync",
"email_sender_address": "\"Janrain Console\" "

Suppose you now run the following command, which changes the email_sender_address property:


{
     "email_sender_address": "admin@janrain.com"
}

That command will change the email_sender_address property. However, it will also delete the email_method property, because that property was not included in the API call. As a result, your global settings will now contain just one property:

"email_sender_address": admin@janrain.com"

Authentication

This endpoint supports Basic authentication.

How to Create an Authentication String

Base URL


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

Allowed regions are:

Sample Request URL


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

Sample Request (curl)

This command updates the settings for the application with the ID htb8fuhxnf8e38jrzub3c7pfrr.


curl -X PUT \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg' \
  -H 'Content-Type: application/json' \
  https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/settings \
  -d '{{
   "custom": {
       "site_locale":"US"
    },
   "email_method": "ses_sync",
  }
  '

Running this command in Postman

Responses

200 OK

If your call to this endpoint succeeds, you'll get back the current settings and setting values for the specified application:


{
   "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/settings",
   "custom": {
       "site_locale": US"
    },
   "email_method": "ses_sync",
   "email_sender_address": "\"Console\" ",
}

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> is not a valid string. This typically occurs if you use a blank space anywhere in the setting name.
400	Error Message: <setting key> must be a boolean value. Indicates that the setting in question only accepts true/false values.
400	Error Message: <setting key> must be valid json. Indicates that the setting in question only accepts JSON values.
400	Error Message: <setting key> must be an integer. Indicates that the setting in question only accepts integer values.
400	Error Message: value is supplied that does not pass additional validation rules defined for the specified key Verify validation rules for the setting and try the 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: Application ID not found. You did not provide a valid application ID.

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


{
   "errors": "Authentication required."
}

How to Create an Authentication String

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.

Before you actually try your authentication string, 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.

GET

PUT

Running this Command in Postman

How to Create an Authentication String