Modify Client Settings

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


'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 request 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": "600",
    "verification_code_lifetime": "600",
    "_global": {
        "rpx_realm": "greg-stemp",
        "user_search_query_fields": "[\"created\", \"displayName\", \"email\", \"lastUpdated\", \"uuid\"]",
        "user_distinguisher_field": "",
        "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": "400",
    "verification_code_lifetime": "400",

Note that the first three settings – site_name, login_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.

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:



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:

Allowed regions are:

  • us 
  • eu 
  • au 
  • sa 
  • cn
  • sg

Sample Request (curl)

This command updates the site_name setting for the API client xyv3q7xhces2yy7cumgrte24epx4m2st.

curl -X PUT \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg'\
  -H 'Content-Type: application/json' \ \
  -d '{
   "site_name":"Documentation Test Site"

 Running this command in Postman


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"

Error Codes

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

Error Code



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.


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.


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

The specified can only be set to true or false.


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

The specified key must use the JSON syntax.


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

The specified key only accepts integer values.


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.


Error Message: Authentication required.

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


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