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
- PUT
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:
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:
- us
- eu
- au
- sa
- cn
- sg
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. |
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:
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:
- us
- eu
- au
- sa
- cn
- sg
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."
}