API Clients and Permissions

API clients control access to the Registration API. The features that are applied to an API client control the base level of read and write access it will have to user records and application management functionality. Additional access control can be put in place with client access schemas.

Client Feature Sets

The following features may be set for an API client. If client features are not set on creation, they can be added or updated through the Janrain dashboard or using the /clients/set_features endpoint.

Feature Description
access_issuer This type of client has permission to issue access tokens scoped for use with all clients.
direct_access This type of client has read and write access to all user records using the client ID and secret.
direct_read_access This type of client has read access to all user records using the client ID and secret.
login_client This type of client is scoped with read and write access to only the currently authenticated user. It can only be used with sign-in and registration based API endpoints. All client-side API calls should be made using a client with this feature.
metadata This type of client will not update the lastUpdated attribute when posting updates to a user record. This client feature set is commonly used with third-party integrations. This type of client can only be provisioned by the Janrain team.

Note: Do not update a client with the metadata feature through the Janrain dashboard - this will remove the feature and may cause unexpected results.
owner This type of client has complete admin access to the application. The application owner credentials should only be used for administrative configuration purposes, such as provisioning additional API Clients, updating client settings, and managing your schema. This type of client cannot be created through the Janrain dashboard, only using the Janrain API.

Client Access Schemas

API clients can also be restricted with read or write access to a subset of specific attributes within an entity type. Custom access schemas are commonly used for integrations with third-party applications. This allows controlled access to the user database based on the attributes that an application needs access to. This is configured on a per-client basis using the /entityType.setAccessSchema endpoint.

Access schemas

This diagram provides some more context about how authorization can be managed for API clients. Integrations with other systems such an Email Service Provider, Ad Server, or CRM make use of API clients can query the database and receive result sets used for data synchronization or data analysis efforts. Each of these clients can be granted access to only the attributes needed to support their specific business need as opposed to providing access to the whole record.

Within the diagram:

  • The API Client assigned to the Email Service Provider only has access to the user’s email address, first name, and opt-ins.
  • The API Client assigned to the Ad Server only has access to the user’s DOB and gender.
  • The API Client assigned to the Recommendation Engine only has access to the user’s Interests.

API Client Settings

API clients also control site-specific behavior and data collection when users interact with the Registration UI or OAuth API endpoints through the flow configuration layer. Default Settings will be applied to all API clients unless overridden at the API client level. Settings can be managed through the Janrain dashboard or using the /settings endpoints.

Below is a list of settings available for use with the Registration experience. Additional settings may also be created for use within custom email templates; see Email Template Variables for more info.

backplane_bus

The name of the backplane bus. For Backplane versions 1.* only.

backplane_password

The Backplane client password. For Backplane versions 1.* only.

backplane_server

The Backplane server your application will be publishing to. For Backplane versions 1.* only.

backplane_username

The Backplane client username. For Backplane versions 1.* only.

backplane_version

The Backplane protocol version you should use. Values available are: v1.0, v1.1, v1.2. For Backplane versions 1.* only.

ex: v1.2

default_flow_name

The flow used in oAuth API endpoints if you do not set the flow parameter.

default_flow_version

The flow used in oAuth API endpoints if you do not set the flow_version parameter.

ex: 20160720205552725054

email_method

Required

Method for generating emails during the registration flow. If Janrain is managing your transactional emails this should always be set to ses_sync. If Janrain is not managing your emails this should always be set to firehose. See the Managing Emails section for more information.

email_sender_address

Default: noreply@janrain.com

This setting specifies the sender email address for transactional emails. Please see Customizing Registration for more information on how to enable a new sender address with Janrain’s email service.

jump_publish_settings

When publishing client settings to the server, this specifies the default settings that will be published in the /settings/widget/publish API call.

ex: {"minimum_age": {"type": "natural"}, "legal_acceptance_URL_2": {"type": "string"}, "legal_acceptance_URL_1": {"type": "string"}}

login_attempts

Default: 6 The number of traditional login or password reset attempts a user can make in a given timespan (see login_attempts_threshold) before getting locked out. This feature is intended for preventing brute force login attacks, so the count includes both successful and failed login attempts.

login_attempts_threshold

Default: 60

The time in seconds before a user’s number of attempts (see login_attempts) counter resets to 0. The counter starts at the beginning of the threshold time period based on a sliding window rather than the exact time of the user’s last attempt.

native_scoped_access

Default: false

When using the oAuth APIs this setting will restrict the response on a successful login or registration to the attributes defined in the userData object in the flow specified in the call.

ex: true

password_recover_url

Required

The base url for generating the link with a one-time authorization code for the password reset email. This corresponds to the {*password_recover_url*} JTL tag in the email template.

ex: http://www.example.com/reset-password.html

postLoginScreens

Required

If your flow has been configured to utilize post login screens this is a comma-separated list defining the order in which the screens should be evaluated.

ex: registrationUnderage,requirementsPostLogin,legalAcceptanceScreen

recover_code_lifetime

Default: 1 day

Sets the duration, in seconds, that the password recover link is valid.

ex: 3600

rpx_app_id

Required

The unique identifier of your Social Login application. This can be found in the settings page of your Social Login dashboard.

ex: 12345678910111213141516

rpx_custom_realm

The realm of your Social Login application if you are using a custom subdomain. This is the fully-qualified domain name aliased to a Janrain endpoint. See Customizing Your Application Domain for more information. If you are using a standard Janrain domain, see rpx_realm.

ex: signin.your-site.com

rpx_key

Required

The API key (secret) of your Social Login application. This can be found in the settings page of your Social Login dashboard.

ex: 123abcd456edfg

rpx_realm

Required

The realm of your Social Login application if you are using a standard Janrain domain. This is identifiable as the subdomain to rpxnow.com in your application domain. If you are using a custom subdomain, see rpx_custom_realm.

ex: your-app

rpx_server

Default: https://rpxnow.com

The server URL of the Social Login application. It should always be set to https://rpxnow.com

site_name

Used in email templates to specify the name of the site where the email was triggered from.

ex: “Welcome to My Website

user_entity_type

Default: user

This setting determines the entity type (schema table) that this client ID will use to read and write data.

ex: my_custom_entity_type

verification_code_lifetime

Default: 1 day

Sets the duration, in seconds, that an email verification code is valid.

ex: 3600

verify_email_url

Required

The base url for generating the link with a one-time code used for email verification. This corresponds to the {*email_verification_url*} JTL tag in the email template.

ex: http://www.example.com/verify-email.html

Managing API Clients and Settings

API clients and settings can be managed through the Janrain dashboard or APIs. See below for step-by-step instructions for each option available in the dashboard and the corresponding APIs that can be used instead. Additional endpoints for managing clients and settings are also available in the API documentation.

Creating New API Clients

Follow the steps below to create a new API client through the Janrain dashboard:

  1. Log in to dashboard.janrain.com.
  2. Click on the Registration icon next to a property to launch the Registration dashboard.
  3. Navigate to the API Clients section.
  4. Click the Create New Client button.
  5. Enter a name for the API client.
  6. Select the checkbox for the feature set to be enabled. Note that some features can be combined, but the login_client feature may not be selected with any other feature.
  7. Click the Generate ID & Secret button.
  8. Copy the Client ID that is generated for use in a later step. (Note: Do not share or communicate the Client Secret.)

Please refer to the /clients/add endpoint for information on how to create new clients via API.

Updating API Clients

Follow the steps below to update the name or feature set of an API client through the Janrain dashboard:

  1. Log in to dashboard.janrain.com.
  2. Click on the Registration icon next to a property to launch the Registration dashboard.
  3. Navigate to the API Clients section.
  4. Click on the API client you want to update.
  5. Click the Edit button.
  6. Update the client name and features as desired.
  7. Click the Save button.

Deleting API Clients

Follow the steps below to delete an API client through the Janrain dashboard:

  1. Log in to dashboard.janrain.com.
  2. Click on the Registration icon next to a property to launch the Registration dashboard.
  3. Navigate to the API Clients section.
  4. Click on the API client you want to update.
  5. Click the Edit button.
  6. Click the Delete button.
  7. Click the OK button in the alert window to confirm.

Resetting API Client Secrets

API client secrets cannot be reset through the Janrain dashboard. You must use the /clients/reset_secret endpoint to perform this action.

Note that if you need to reset the owner API client secret, Janrain must also update a configuration in the Janrain dashboard. Please open a support ticket notifying Janrain of this update.

Adding API Client Settings

Follow the steps below to add API client settings through the Janrain dashboard:

  1. Log in to dashboard.janrain.com.
  2. Click on the Registration icon next to a property to launch the Registration dashboard.
  3. Navigate to the Settings section.
  4. Find the name of the API client for which you want to add settings.
  5. Click on that client name.
  6. Enter the setting key in the box to the left and the setting value in the box to the right.
  7. Click the Save button.
  8. The page will refresh.

Please refer to the /settings/set, /settings/set_multi, and /settings/set_default endpoints for information on how to create and update settings via API. When creating a new setting key, the API will return false as a successful response, indicating that the key did not already exist.

Updating API Client Settings

Follow the steps below to update the value for an existing API client setting through the Janrain dashboard:

  1. Log in to dashboard.janrain.com.
  2. Click on the Registration icon next to a property to launch the Registration dashboard.
  3. Navigate to the Settings section.
  4. Find the setting that you want to update.
  5. Click on that setting name.
  6. Enter the new setting value in the box that appears.
  7. Click the Save button.
  8. The page will refresh.

Note that you cannot edit the key name for an existing setting. To update the key name, you must first delete the setting and add it again with the full key/value pair. See the section below for details on deleting settings.

Please refer to the /settings/set, /settings/set_multi, and /settings/set_default endpoints for information on how to create and update settings via API. When updating an existing setting key, the API will return true as a successful response, indicating that the key already existed.

Deleting API Client Settings

  1. Log in to dashboard.janrain.com.
  2. Click on the Registration icon next to a property to launch the Registration dashboard.
  3. Navigate to the Settings section.
  4. Find the setting that you want to delete and hover over the name.
  5. Click the Delete icon that appears.
  6. Click the OK button in the alert window to confirm.
  7. The page will refresh.

Please refer to the /settings/delete and /settings/delete_default endpoints for information on how to delete settings via API.

Scroll ↓