Managing Applications

You can think of an application as being a collection of properties, with properties being used for making authenticated requests against the Janrain REST APIs. Applications provide a way to centrally manage all of your properties; for example, you can configure a collection of settings at the application level and, by default, have those values applied to each of your properties. In turn, you can then update any of those settings at the aplication level, and then have those settings automatically applied to all of your properties.

The Managing Applications section of the documentation includes the following topics:

Viewing Application Information

Information about your application can be found at the top of the Manage Application page; this information includes the Application ID (which does not need to be kept secret), the application region, and the application’s Registration and Single Sign-On (SSO) domains:

The Manage Application Page

In some cases, the wording for the Registration Domains might look like this:

documentation-1.janrain.com, and 3 more

The term and three more indicates that there are additional registration domains that couldn’t be displayed onscreen. If an application has more than one configured domain, you can display a list of all the domains by clicking the View all domains icon. When you do that, a dialog box appears listing all your registration and SSO domains.

Managing Global Settings

As noted previously, applications typically contain multiple properties, with each property representing a specific level of API access. Properties also have a collection of API client settings that specify such things as the default flow name and locale, the email address used for transactional emails (i.e., messages sent after registration or from the Console itself, such password reset notifications), and the URL used to verify user email addresses. These settings enable you to create properties that have the same access level (e.g., login_client) but differ in functionality.

With some exceptions, settings can be applied at either the global (application) scope or the local (individual property) scope. For example, the {entity_type}_distinguisher_field_values setting (which restricts agent access to user profiles) can only be set at the global scope. However, other settings can be configured at the local scope, meaning that different properties might have different values for the same setting.

For example, suppose you have an application with three properties:

  • Property A
  • Property B
  • Property C

You can configure each of these properties to use a different login_attempts value: Property A could allow a maximum of 4 login attempts; Property B could allow a maximum of 5 login attempts; and Property C could allow a maximum of 9 login attempts. Different properties can have different configuration settings.

Of course, that leads to an obvious question: what happens if a setting is configured at the global scope, but that same exact setting is configured differently at the local scope? When settings conflict, who wins?

In a nutshell, here’s the answer:

  • If a setting is not configured at all (that is, at either the global scope or the local scope), then the platform default value for that setting is used by all properties. For example, if login_attempts is not configured at either the global scope or the local scope, then all properties will allow a maximum of 6 login attempts. That’s because 6 is the default value applied at the Janrain platform level.

    Note. Some settings (such as email verification or password reset URLs) don’t have a default value. If one of those settings is not configured at either the global scope or the local scope then that setting won’t have a value.

  • If a setting is configured at the global scope but is not configured at the local scope, then the global value is used. For example, suppose login_attempts is set to 5 at the global scope, but is not configured at the local scope for Property A. In that case, Property A will allow a maximum of 5 login attempts: the value configured at the global scope. By default, properties inherit the values configured at the global scope.

  • If a setting is configured at the local scope, then that value is used regardless of whether or not the setting is configured at the global scope. For example, suppose login_attempts is set to 5 at the global scope, but is set to 8 for Property A’s local scope. In that case, Property A will allow a maximum of 8 login attempts: values at the local scope override values configured at the global scope.

In other words:

Setting Default Value Global Scope Local Scope Effective Value
login_attempts 6 5 - 5 – The global scope value is inherited by the property.
login_attempts 6 - 8 8 – The local setting is used when there is no global setting.
login_attempts 6 5 8 8 – The local setting overrides the global setting.
login_attempts 6 - - 6 – When a setting is not specified at the global scope or the local scope, the default value is used.

The following topics provide step-by-step instructions for managing global settings:

Viewing Global Settings

Global settings are found on the Manage Application page and are grouped by predefined setting categories. For example, the Transactional Email settings might look like this:

Sample Settings

Custom settings configured at the global scope can also be viewed from the Manage Application page. Custom settings are any settings (in a name/value format) that are not defined on the API Clients and Permissions page. For example:

Custom Settings

Note. What if a setting doesn’t appear on the Manage Applications page? That’s fine: it simply means that the setting hasn’t been defined at the global scope.

Modifying Global Settings

To modify a global setting, click Edit Settings:

The Edit Settings Button

That takes you to the Edit Settings page:

The Edit Global Settings Page

Note. If you can access the Manage Application page but you don’t see the Edit Settings button, that means that you don’t have permission to modify the global settings. To get that permission, you’ll need to be assigned a different Console role.

To edit an existing setting, select the current value and then type in a replacement value. For example, to change the custom setting min_age from 13 to 16, simply select 13 and then type 16:

A Custom Global Setting

In some cases (for example, the email_method setting), you might be able to select a new value from a dropdown list; this occurs when there are a limited, and predefined, set of values you can choose from:

Using a Setting Dropdown List

After making all your changes, click the Save Changes icon:

The Save Settings Button

If you leave the Edit Settings page without saving your changes, those changes won’t be saved.

Adding a New Setting

To add a new global setting, complete the following procedure:

  1. Click the Add Setting icon:
    The Add a Setting Button
  2. To add a standard Janrain setting, in the Edit Settings pane, click Select setting key and then click the setting you want to add:
    Adding A New Setting
    Any time the Select setting key list is displayed, you can begin typing and the Console will find all the settings that match what you type.
  3. In the Value field, enter the value for the new setting:
    Configuring a Setting Value
  4. To add a custom setting, type the setting name in the Select setting key field. Note that setting names cannot contain blank spaces; individual words in a name are typically separated by using underscores (my_setting_name):
    Adding a Custom Setting
  5. As you type, the setting name appears in the Create setting button located just above the new setting. Click (in this example) Create site_locale. If you click anywhere other than Create site_locale, you’ll see an error message similar to this:
    An Incorrectly-Added Setting
    To resolve this error, click the setting name (site_locale) and then click Create site_locale. You won’t be able to save your changes until this error has been resolved.
  6. After adding the custom setting, type the setting value in the Value field:
    Configuring a Custom Setting Value
  7. When you are finished adding new settings, click the Save Changes icon:
    The Save Changes Button

Removing a Global Setting

To remove a global setting, click the trash can icon located to the left of the setting you want to delete:

Removing a Setting

When you click the trash can icon, the setting disappears from the screen, and you won’t be presented with any sort of confirmation dialog box. However, to actually delete the setting from the application you must click Save Changes:

The Save Changes Button

If you leave the Edit Settings page without saving your changes, the setting will not be deleted.

Accessing Property Settings

From the Manage Application page you can quickly access setting pages for any of your properties. To access these settings, start by finding the Properties List:

Accessing Property Settings

From there, click the appropriate property name to go to the property’s Edit Property page:

The Manage Properties Page

On that page yu can view all your property settings and, if necessarym click Edit Settings to update any of thoe setting values.

Scroll ↓