Modify Application Settings

Endpoint URL: {identityDomain} /config/{appId} /settings


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"


Respects the API Client Allow List:  Yes


API Client Permissions

The following table indicates the API clients that can (and the API clients that can't) be used to call this endpoint:

owner
access_issuer
direct_access
direct_read_access
login_client
Yes
No
No
No
No


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."
}