Janrain Configuration API v1 Documentation

Clients and Settings Overview

The Clients and Settings APIs are primarily used to manage your API clients (also known as "properties"). For example, these endpoints enable you to do such things as:

  • Create new API clients
  • Delete existing API clients
  • Modify the settings and permissions assigned to your API clients at either the global scope or the local (individual client) scope

In addition, several of the endpoints in this collection can be used to return information about your entity types (user databases).

These new endpoints supercede the previous collection of Janrain Clients and Settings APIs. The previous endpoints (now referred to as the "legacy" Clients and Settings APIs) remain valid, and the documentation for these endpoints can still be found here. However, we strongly recommend that, as time allows, you begin to migrate to the new Clients and Settings APIs detailed on this page.

Why? Two reasons. For one, the new Clients and Settings APIs adhere to the RESTful API standards; that wasn't always true for the legacy APIs. For another, the new APIs are part of Janrain's Configuration API (CAPI). Eventually, CAPI will provide consistency across all the Janrain APIs: regardless of the API or the endpoint, you'll use the same authentication method, employ the same request and response formats, see the same error messages, etc. Switching to the new Clients and Settings APIs now will give you a headstart when additional CAPI APIs are released in the future.

Adding / Updating Fields

Common Field Attributes

All fields share a set of common attributes:

  • type - required

    The type of field that you wish to create or update. Currently supported field types are:

    Click on one of the types for a full example of a field definition.

  • name - required

    A unique name used to identify the field (cannot contain spaces).

    Example:

    "name": "myCoolField"
  • schemaAttribute - required

    A path to the schema attribute in the profile record to which this field's value should be mapped. Make a call to /config/{app}/schemas/{schema} for a list of valid values.

    Example:

    "schemaAttribute": "primaryAddress.phone"
  • label - optional

    An optional field label used by the Janrain Registration widget. It is not necessary for pure API implementations. It must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

    Example:

    "label": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    }
  • tip - optional

    An optional field tooltip that is used by the Janrain Registration widget. It is not necessary for pure API implementations. It must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

    Example:

    "tip": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    }
  • validation - optional

    An optional list of validations that should be applied to this field. Validations have the following attributes:

    • rule - required

      The name of the validation rule to apply. Must be one of the validations allowed for this field's type. See this table to determine which validations are available to a given field type.

    • value - required

      The value to use for validation. For some validations this will just be true or false (for example, required). For others this will be a configuration value for the validation. See the validations section for more information on how to configure each validation.

    • message - required

      The error message to be used if the validation fails. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

      Note: Message is not supported by the matchOptions validation, but is required for all others.

    Example:

    "validation": [
      {
        "rule": "required",
        "value": "true",
        "message": {
          "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
        }
      }
    ]

Type-specific Field Attributes

Each type of field has additional parameters specific to it. Refer to the table at the end of this section to see which attributes apply to which fields.

  • socialProfileData - optional

    When a user logs in using a social provider, Janrain's Social Login service returns the social provider in the form of a Portable Contact payload. You can use the socialProfileData attribute to specify which data from the social profile should be used to populate the value for this field in the Janrain user record.

    Example:

    "socialProfileData": "profile.name.familyName"
  • placeholder - optional

    This is used as the placeholder attribute on form elements when using the Janrain widget. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

    Example:

    "placeholder": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    }
  • preChecked - optional

    This only applies to the checkbox field type. If set to true, the checkbox will appear pre-checked to new users registering with the Janrain widget. This is useful if you want to require that users specifically opt out of something (for example, a newsletter).

    Example:

    "preChecked": true
  • submitValue - optional

    This only applies to the checkbox field type. Use this if you need to specify the submit value of a check box (that is, the check box should submit a value other than "on").

    Example:

    "submitValue": "true"
  • options - required

    For the radio and select fields, you must define the options to be displayed. Options have the following attributes:

    • disabled - optional

      Set this to true to disable the option.

    • label - required

      The label to display for this option. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

    • selected - optional

      Set this to true to select this option by default. Only one option in a field can have this attribute.

    • value - required

      The value of this option.

      Example:

      "options": [
        {
          "selected": true,
          "label": {
            "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
          },
          "value": "waffles"
        }
      ]
text email password checkbox radio select textarea
socialProfileData yes yes - - - - yes
placeholder yes yes yes - - - yes
preChecked - - - yes - - -
submitValue - - - yes - - -
options - - - - yes yes -

Validations

Each field supports a subset of the validations available. Refer to the table at the end of this section to determine which validations are available to you.

  • blacklist - Takes a list of disallowed strings as its value.

    Example:

    {
      "rule": "blacklist",
      "value": [ "do not allow this", "or_this!" ],
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • format - Asserts that the field conforms to a certain format. It takes one of the following predefined formats as its value:

    Example:

    {
      "rule": "format",
      "value": "email",
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
    • alpha - Only allows alphabetic characters, and must contain at least one character. Defined as /^[a-z]+$/i.

    • alphaExtended - Only allows alphabetic characters, dashes (-), and single quotes('). The field value must contain at least one character. Defined as /^[a-zA-Z\-']+$/.

    • alphaExtendedSpaces - Only allows alphabetic characters, dashes (-), single quotes('), and whitespace characters (\r, \n, \t, and \f). Defined as /^[a-zA-Z\-'\s]+$/.

    • alphaNumeric - Only allows alphabetic and numeric characters. The field value must contain at least one character. Defined as /^[a-z0-9]+$/i.

    • alphaNumericExtended - Only allows alphabetic and numeric characters. Allows for dashes (-), underscores (_), and periods (.) within the value, so long as they are not at the beginning or the end. The field value must contain at least three characters. Defined as /^[a-z][-a-z0-9\s_.]*[a-z0-9]$/i.

    • email - Only allows valid email addresses. Defined as /^.+@(?:[^.]+\.)+(?:[^.]{2,})$/.

    • i18nAlphaNumeric - Allows only alphanumeric characters without excluding characters containing accents (for example, é). Defined as /^[^-\s^`~!@#$%^&*()_=+\[{\]}\|;:‘“,<.>/?]+$/, it disallows the following characters:

      • whitespace characters (\r, \n, \t, and \f)
      • dashes (-)
      • carets (^)
      • backticks (`)
      • exclamation points (!)
      • at signs (@)
      • number signs (#)
      • dollar signs ($)
      • percent signs (%)
      • ampersands (&)
      • asterisks (*)
      • parentheses (())
      • underscores (_)
      • equal signs (=)
      • plus signs (+)
      • square brackets ([])
      • curly braces ({})
      • pipes (|)
      • semicolons (;)
      • colons (:)
      • single quotes (')
      • double quotes (")
      • commas (,)
      • angle brackets (<>)
      • periods (.)
      • forward slashes (/)
      • question marks (?)
    • noWhitespace - Disallows whitespace characters (\r, \n, \t, and \f). Defined as /^\S*$/.

    • numeric - Only allows numeric characters. Defined as /^(\d+)$/.
    • numericReal - Only allows real number values. Defined as /^(\d+\.?\d*|\.\d+|\-\d+\.?\d*|\-\.\d+)$/, it allows numbers in the following formats:

      • 1234
      • 12.34
      • .1234
      • -1234
      • -12.34
      • -.1234
    • phone - Only allows valid phone numbers. Defined as /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/, it allows phone numbers in the following formats:

      • (123)-456-7890
      • (123).456.7890
      • (123) 456 7890
      • 123-456-7890
      • 123.456.7890
      • 123 456 7890
    • phoneInternational - Similar to the phone validation, but allows for an optional one to four preceding numbers. Defined as /^(\d{1,4}[-. ]?)?\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/.

    • zipCode - Only allows five character numeric values. Defined as /^\d{5}$/.
    • zipCode+4 - Similar to the zipCode validation, but allows for an optional plus-four code. Defined as /^\d{5}(\-\d{4})?$/.
  • match - Asserts that a field value matches the value of another field. Its value must be set to another existing field.

    Example:

    {
      "rule": "match",
      "value": "confirmPasswordField",
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • matchOptions - Protects against invalid input on select fields by enforcing that the value submitted be one of the options defined in the field. Set this to false only if you plan on dynamically populating the select options yourself. This is added to select fields by default.

    Example:

    {
      "rule": "matchOptions",
      "value": True
    }
  • maxLength - Asserts that the value of a field is at most the length set as the value of this validation.

    Example:

    {
      "rule": "maxLength",
      "value": 30,
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • minLength - Asserts that the value of a field is at least the length set as the value of this validation.

    Example:

    {
      "rule": "minLength",
      "value": 4,
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • minYears - Asserts that the value from a dateselect field is at least so many years in the past.

    Example:

    {
      "rule": "minYears",
      "value": 18,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  • required - Asserts that a value is provided for this field. Set to true to enable this validation.

    Example:

    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • unique - Asserts that the value of this field is unique when compared to all records within the Janrain application. Set to true to enable this validation.

    Example:

    {
      "rule": "unique",
      "value": true,
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • whitelist - Takes a list of allowed strings as its value. All other strings are disallowed.

    Example:

    {
      "rule": "whitelist",
      "value": ["only allow this", "or_this_one!"],
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • clientFunctionName - Name of the function to use for validation on the client.

    Example:

    {
      "rule": "clientFunctionName",
      "value": "functionName",
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  • serverRegexSetting - Server Setting of regex to use for validation.

    Example:

    {
      "rule": "serverRegexSetting",
      "value": "serverRegexSetting",
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
checkbox dateselect email password radio select text textarea
blacklist - - - - - - yes -
format - - yes* yes - - yes yes
match - - yes yes yes yes yes -
matchOptions - - - - - yes - -
maxLength - - yes yes - - yes yes
minLength - - yes yes - - yes yes
minYears - yes - - - - - -
required yes yes yes yes yes yes yes yes
unique - - yes - - - yes -
whitelist - - - - - - yes -
clientFunctionName - yes yes yes - yes yes yes
serverRegexSetting - yes yes yes - yes yes yes

*: Fields of type email check for correctly-formatted emails by default. This cannot be overridden.

Full Examples

Full Example: checkbox

{
  "type": "checkbox",
  "name": "myCustomCheckboxField",
  "schemaAttribute": "optIn.status",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "preChecked": true,
  "submitValue": "yes",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: dateselect

{
  "name": "birthdate",
  "schemaAttribute": "birthday",
  "type": "dateselect",
  "label": {
    "key": "8122c314a4e9d558f6d3eedfb2446376"
  },
  "yearLabel": {
    "key": "acb8b9cedb63cb5930bae0fb1c2d50cc"
  },
  "monthLabel": {
    "key": "ace9326798de56c595568a7a4141972c"
  },
  "dayLabel": {
    "key": "6f44a1db770c928b0d40bb980548f43d"
  },
  "monthNames": [
    {
      "key": "66fcba24722d94d03167df4d29a3fcde"
    }, {
      "key": "eec9c536de325f7f66669a7a61a55fc0"
    }, {
      "key": "b8a35f47cfde6c15643c74804f9a6421"
    }, {
      "key": "399c58387be99853b53ffc4f778814ab"
    }, {
      "key": "ab66d779cf23720afbc4f2c49a296728"
    }, {
      "key": "9089a6c3cc7b9d447c5aa870a38a49bf"
    }, {
      "key": "24ea0188feb2be9c0a6fc0fffa329009"
    }, {
      "key": "f814c7e7884980bfbe637bc8b7d5a798"
    }, {
      "key": "cbbd277bc1b7f3034d4b8a5fc7c0a717"
    }, {
      "key": "17ef13bbd9bd987fc16b4a26665e99ce"
    }, {
      "key": "dd1b34fbac69ea3440260d0b25f660ea"
    }, {
      "key": "368ace206c6cd848a8eb028fcf44a895"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }, {
      "rule": "minYears",
      "value": 18,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Full Example: email

{
  "type": "email",
  "name": "myCustomEmailField",
  "schemaAttribute": "email",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.email",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: password

{
  "type": "password",
  "name": "myCustomPasswordField",
  "schemaAttribute": "password",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "minLength",
      "value": 16,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }, {
      "rule": "match",
      "value": "myCustomPasswordConfirmField",
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Full Example: radio

{
  "type": "radio",
  "name": "myCustomRadioField",
  "schemaAttribute": "favorites.breakfastFood",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "options": [
    {
      "selected": true,
      "label": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      },
      "value": "waffles"
    },
    {
      "label": {
        "key": "c8050744-9b1d-4360-89e7-b37802d59c4a"
      },
      "value": "pancakes"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: select

{
  "type": "select",
  "name": "myCustomSelectField",
  "schemaAttribute": "favorites.lunchFood",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "options": [
    {
      "selected": true,
      "label": {
        "8a8508aa-f939-472b-bad2-59f6c0089a60"
      },
      "value": "hotdogs"
    },
    {
      "label": {
        "c8050744-9b1d-4360-89e7-b37802d59c4a"
      },
      "value": "hamburgers"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: text

{
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.displayName",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }, {
      "rule": "unique",
      "value": true,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Full Example: textarea

{
  "type": "textarea",
  "name": "myCustomTextareaField",
  "schemaAttribute": "profileBlurb",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.aboutMe",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "maxLength",
      "value": 500,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Modifying Forms

You can add or remove fields from forms. Doing so allows you to control what data may be included in the form submissions to your Capture application. Forms can also have features, which add different types of functionality to forms.

Form Features

Currently, the only feature available to forms is captcha. The captcha feature adds Google reCaptcha to the form rendered by the Capture widget.

Below is an example of a form with captcha enabled:

{
  "features": [
    {
      "name": "captcha"
    }
  ],
  "fields": [
    {
      "name": "firstName",
      "required": true
    },
    {
      "name": "lastName",
      "required": true
    }
  ]
}

Security Schemes

Basic Authentication basic

Config API supports basic HTTP authentication using your Capture owner credentials. To create the authorization code, combine your client ID and secret like this client_id + ":" + secret, then base64 encode the result.

Authorization string

Used to send the authorization code.

Example: Authorization: Basic aW1fYV9saXR0bGVfdGVhX3BvdF9zaG9ydF9hbmRfc3Q6b3V0X2hlcmVfaXNfbXlfaGFuZGxlX2hlcmVfaXNfbXk=

Responses

401 Unauthorized

A request was made without credentials or the credentials were invalid.

403 Forbidden

The credentials provided were incorrect for the requested resource.

Endpoints

https://{version}.api.{region}.janrain.com

URI Parameters

region string required

The region that corresponds with the location of your Capture application. NOTE--for China, {version} is temporarily rebuild-{version} (for example, v1 for China would be https://rebuild-v1.api.cn.janrain.com).

Possible values:
  • us
  • eu
  • au
  • sa
  • cn
version string required
Possible values:
  • v1

/config/{app}

URI Parameters

app string required

The Capture application ID.

get

Description

Returns flows and schemas configured for this app.

Security

Responses

200 OK

Response Example (application/json)
{
  "_relationships": {
    "entityTypes": [
      {
        "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/entityTypes/user",
        "name": "user"
      }
    ]
    "flows": [
      {
        "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/standard",
        "name": "standard"
      }
    ],
    "schemas": [
      {
        "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/schemas/user",
        "name": "user"
      }
    ]
  },
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz",
  "name": "v86cchggr5cdvbfh7ydk8s63zz"
}

404 Not Found

Capture application could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Capture application not found."
}

/config/{app}/clients

Description

API clients serve two major purposes: they make authenticated requests against the Janrain REST APIs, and they (or, more specifically, API clients that have the login_client feature set) are used to authenticate users during logon and registration. In the Janrain Console, you can find your API clients on the Manage Properties page.

The /config/{app_id}/clients endpoint enables you to return information about all the API clients associated with an application. In addition, the POST method enables you to create a new API client.

This endpoint includes the following methods:

  • GET
  • POST

get

Description

Returns permission and metadata information for all your API clients. The returned data includes:

  • _self. Configuration endpoint for the API client. For example, suppose your configuration domain is https://v1.api.us.janrain.com/ and the _self value for a client is /config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xj2dmg2mqsm6a8gx89cwn3fu929p4pd. Combining those two values gives you the configuration endpoint for managing that client (adding/modifying property values, deleting the client, etc.): https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xj2dmg2mqsm6a8gx89cwn3fu929p4pdm
  • _id. The API client ID.
  • _secret. The API client secret (i.e., client password). Client secrets should never be publicly exposed.
  • _settings. Configuration endpoint for the API client settings.
  • name. Name (and description) of the API client.
  • ipWhitelist. Collection of IP addresses allowed to interact with the client; for example, the address 192.168.1.0/24 allows access to IP addresses 192.168.1.0 through 192.168.1.255. The default value is 0.0.0.0/0, which allows access to all IP addresses.
  • features. Client features associated with the API client; a single client can be associated with more than one feature.

Your API call must have the owner client permission in order to return data for all your clients.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients

Sample Request (curl)

This command returns information about all the API clients associated with the specified application:

curl -X GET \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients \
  -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' 

Query Parameters

has_feature string

Enables you to return only those API clients that have the specified feature sets. Each filter set you want to filter on is passed in a has_feature parameter; for example, this syntax returns only the API clients that have the login_client feature set:

has_feature=login_client

Meanwhile, this syntax returns all the API clients that have both the direct_access and the access_issuer feature sets:

has_feature=direct_access&has_feature=access_issuer

Responses

200 OK

If your call to this endpoint succeeds, you'll get back information similar to this for each of the API clients associated with the specified application:

[
    {
        "_id": "ay6e3qmucvdyr29hmpvxjdjupe8bcsky",
        "_secret": "u4bhgr4vsqde7ju53aubmptfbneolk7",
        "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/ay6e3qmucvdyr29hmpvxjdjupe8bcsky",
        "_settings": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/ay6e3qmucvdyr29hmpvxjdjupe8bcsky/settings",
        "features": [
            "owner"
        ],
        "ipWhitelist": [
             "0.0.0.0/0"
        ],
        "name": "North America Login Client"
    },
    {
        "_id": "ed7absqep5rffbmqx89c9mwexqvbnfnk",
        "_secret": "dre5hgdtvj5ush09ii7tfrf968buwt6gs",
        "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/ed7absqep5rffbmqx89c9mwexqvbnfnk",
        "_settings": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/ed7absqep5rffbmqx89c9mwexqvbnfnk/settings",
        "features": [
            "login_client"
        ],
        "ipWhitelist": [
            "0.0.0.0/0"
        ],
        "name": "Default Login Client"
     },
     {
        "_id": "nhjsdtjwvaytevc2w5sx42skggvjn7bu",
        "_secret": "rssq9iree8vcgh4pppcumnh7qy44qpz",
        "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu",
        "_settings": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu/settings",
        "features": [
            "login_client"
        ],
        "ipWhitelist": [
            "0.0.0.0/0"
        ],
        "name": "This is a client description"
    }
]

401 Unauthorized

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

404 Not Found

Client ID not found. You did not provide a valid client ID.

post

Description

Creates a new API client.

To create a new API client, you must specify the client properties in the request body of your API call. Those client properties include:

  • name. The only required property. Note that the name you give the new client must be unique across the application. For example, if you already have a client named Test Client, your API call will fail if you try to create another client with the name Test Client.
  • ipWhitelist. JSON array of Classless Inter-Domain Routing IP addresses; only the addresses included on the whitelist will be able to interact with the new client. If you do not include the ipWhitelist property then the value will automatically be set to 0.0.0.0/0, which allows any IP address to interact with the client.
  • features. Specifies the client feature (or features) associated with the new API client. Available features include:

    • access_issuer. Issues access tokens scoped for use with all API clients.
    • direct_access. Has read/write access to all user records.
    • direct_read_access. Has read-only access to all user records.
    • login_client. Has read/write access to the user record for the current user. This client is typically used for login and registration. API clients that have the login_client feature cannot be associated with any other feature (i.e., a client cannot have the login_client feature and, say, the direct_access feature).
    • metadata. API calls made with this feature do not modify the lastUpdated attribute when they make changes to a user profile; for example, your API call might update the user's displayName or familyName but will not change the lastUpdated attribute. This feature can only be assigned by Janrain: if you try assigning the metadata feature in your API call, that call will fail.
    • owner. Has full administrative access to the application.

You do not have to assign a feature set when you create a new client. However, that client will not have permission to do anything until it has been assigned a feature set.

Both the ipWhitelist and features properties must be passed as JSON arrays. In a JSON array, individual values are enclosed in double quote marks and separated by using commas. In addition, the entire set of values is surrounded by square brackets:

["access_issuer", "direct_access"]

Your API call must have the owner permission in order to create a new client.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients

Sample Request (curl)

This command creates a new API client named Documentation Client. The client can be accessed from any IP address, and is assigned the login_client feature.

curl -X POST \
  https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients \
  -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' \
  -H 'Content-Type: application/json' \
  -d '{    
    "name": "Documentation Client", 
    "ipWhitelist": ["0.0.0.0/0"], 
    "features": ["login_client"] 
}'

Responses

201 Created

If your API call succeeds, you'll see the response code 201 Created as well as property values for the new API client:

{
    "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/3bchk5hsx6v58dkn288nbybmxfyk32u7",
    "name": "Documentation Client",
    "_settings": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/3bchk5hsx6v58dkn288nbybmxfyk32u7/settings",
    "ipWhitelist": [
        "0.0.0.0/0"
    ],
    "_secret": "ltgc4vxdjlsiemvj98gd5h2q7xdjplld",
    "_id": "3bchk5hsx6v58dkn288nbybmxfyk32u7",
    "features": [
        "login_client"
    ]
}

400 Bad Request

  • The metadata feature can only be applied to a client by Janrain. Remove metadata from the list of client features and try the API call again.
  • Clients with the login_client feature cannot have any other features. Remove all the features except _login_client_ from the API call and try again.
  • Missing data for required field. Typically, this means that you failed to specify the client name.
  • Not a valid string. Typically, this means that you did not provide a properly-formatted name. For example, you might have included a special character within the name.
  • Not a valid CIDR address. One or more of the IP addresses on the IP whitelist has been incorrectly formatted.
  • Not a valid feature name. You are limited to the features detailed in the features list.

401 Unauthorized

  • Authentication required. You either failed to provide credentials or you provided invalid credentials. This endpoint requires Basic authentication.

404 Not Found

  • Application ID not found. You did not provide a valid client application ID.

409 Conflict

  • API client already exists. Client names must be unique within an application.

/config/{app}/clients/{client_id}

Description

API clients serve two major purposes: they make authenticated requests against the Janrain REST APIs, and they (or, more specifically, API clients that have the login_client feature set) authenticate users during login and registration. The /config/{app_id}/clients/{client_id} endpoint enables you to:

  • Return information for a specific API client
  • Modify permissions for a specific API client
  • Delete a specific API client

This endpoint includes the following methods:

  • GET
  • PUT
  • DELETE

URI Parameters

client_id string required

get

Description

Returns permission and metadata information for a specific API client, including:

  • _self. Configuration endpoint for the API client. For example, suppose your configuration domain is https://v1.api.us.janrain.com/ and the _self value for a client is /config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xj2dmg2mqsm6a8gx89cwn3fu929p4pd. Combining those two values gives you the configuration endpoint for managing that client (adding/modifying property values, deleting the client, etc.): https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xj2dmg2mqsm6a8gx89cwn3fu929p4pdm
  • _id. The API client ID.
  • _secret. The API client secret (i.e., client password). Client secrets should never be publicly exposed.
  • _settings. Configuration endpoint for the API client settings.
  • name. Name (and description) of the API client.
  • ipWhitelist. Collection of IP addresses allowed to interact with the client; for example, the address 192.168.1.0/24 allows access to IP addresses 192.168.1.0 through 192.168.1.255. The default value is 0.0.0.0/0, which allows access to all IP addresses.
  • features. Client features associated with this API client. Clients can be associated with more than one feature.

Your API call must have the owner permission in order to return client data.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID, and replace nmub5w3rru9k6rzupqaeb7bbwv6jn658 with your client ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/nmub5w3rru9k6rzupqaeb7bbwv6jn658

Sample Request (curl)

This command returns information about the API client with the client ID nmub5w3rru9k6rzupqaeb7bbwv6jn658:

curl -X GET \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/ nhjsdtjwvaytevc2w5sx42skggvjn7bu \
   -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' 

Responses

200 OK

If your call to this endpoint succeeds, you'll get back information for the specified API client. For example:

{
    "_id": "nhjsdtjwvaytevc2w5sx42skggvjn7bu",
    "_secret": "fgt66reekdteb7amqpcuc3cddy4laa2",
    "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu",
    "_settings": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu/settings",
    "features": [
        "login_client"
    ],
    "ipWhitelist": [
        "0.0.0.0/0"
    ],
    "name": "This is a client description"
}

401 Unauthorized

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

404 Not Found

  • Client ID not found or Application ID not found. You did not provide a valid application and/or client ID.

put

Description

Updates permissions and settings for an existing API client. To update an API client, you must specify the client properties in the request body of your API call. Those client properties include:

  • name. The only required property. If you do not specify a name your API call will fail.
  • ipWhitelist. JSON array of Classless Inter-Domain Routing IP addresses; only the addresses included on the whitelist will be able to interact with the client. If you do not include the ipWhitelist property then the value will automatically be set to 0.0.0.0/0, which allows any IP address to interact with the client.
  • features. Specifies the client feature (or features) associated with the API client. Available feature sets include:
    • access_issuer. Issues access tokens scoped for use with all API clients.
    • direct_access. Has read/write access to all user records.
    • direct_read_access. Has read-only access to all user records.
    • login_client. Has read/write access to the user record for the current user. Login_clients are typically used for login and registration, and clients with the login_client feature cannot be associated with any other feature; for example, you cannot have a client that has both the login_client and, say, the direct_access features.
    • metadata. API calls made with this feature do not modify the lastUpdated attribute when they make changes to a user profile; for example, your API call might update the user's displayName or familyName but will not change the lastUpdated attribute. This feature can only be assigned by Janrain: if you try assigning the metadata feature in your API call, that call will fail.
    • owner. Has full administrative access to the application.

You do not have to assign a feature when you update a client. However, doing so deletes all existing features from the client. In turn, that client will not have permission to do anything until it has been assigned a feature.

Both ipWhitelist and features must be passed as JSON arrays. In a JSON array, individual values are enclosed in double quote marks and separated by using commas. In addition, the entire set of values is surrounded square brackets:

["access_issuer", "direct_access"]

Your API call must have owner permissions in order to update a new client.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID, and replace nmub5w3rru9k6rzupqaeb7bbwv6jn658 with your client ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/2grgd9hc949kg7ehqzwzvjgvhddex3rb

Sample Request (curl)

This command updates the API client with the client ID nmub5w3rru9k6rzupqaeb7bbwv6jn658. The client will be renamed Documentation Login Client and will have the login_client feature. Because the ipWhitelist property is not included, that value will be reset to the default value of 0.0.0.0/0. This means that any IP address can interact with the client.

curl -X PUT \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/2grgd9hc949kg7ehqzwzvjgvhddex3rb \
  -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' \
  -H 'Content-Type: application/json' \
  -d '{    
         "name": "Documentation Login Client", 
         "features": ["login_client"] 
      }'

Responses

200 OK

If your API call succeeds, you'll get back the new property values for the API client. These values will look similar to this:

{
    "_id": "3bchk5hsx6v58dkn288nbybmxfyk32u7",
    "_secret": "ccsskpakfgxegv9t5espd28r374txx9j",
    "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/3bchk5hsx6v58dkn288nbybmxfyk32u7",
    "_settings": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/3bchk5hsx6v58dkn288nbybmxfyk32u7/settings",
    "features": [
        "login_client"
    ],
    "ipWhitelist": [
        "0.0.0.0/0"
    ],
    "name": "Documentation Login Client"
}

400 Bad Request

  • The metadata feature can only be applied to a client by Janrain. Remove metadata from the list of features and try the API call again.
  • Missing data for required field or Name not supplied.
  • Not a valid string. Make sure your string value is enclosed in double quotes.
  • Not a valid CIDR address. One of or more of the IP addresses on the IP whitelist has been incorrectly formatted.
  • Not a valid feature name. You are limited to the features detailed in the features list.
  • Clients with the login_client feature cannot have any other features. Remove all the features except _login_client_ and try your API call again.

401 Unauthorized

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

403 Forbidden

  • Clients with the metadata feature can only be updated by Janrain. Contact your Janrain representative for help in modifying this client.
  • Owner feature cannot be removed from the client making the call. After the owner feature has been added to a client, that feature can only by removed by Janrain.

404 Not Found

  • Client ID not found. You did not provide a valid client ID.

409 Conflict

  • API client already exists. Client names must be unique across an application.

delete

Description

Deletes an existing API client. Your API call must have the owner permission in order to delete a client. Note that you cannot delete any API client that has the owner feature.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID, and replace nmub5w3rru9k6rzupqaeb7bbwv6jn658 with your client ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/nmub5w3rru9k6rzupqaeb7bbwv6jn658

Sample Request (curl)

This command deletes the API client with the client ID nmub5w3rru9k6rzupqaeb7bbwv6jn658:

curl -X DELETE \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/nmub5w3rru9k6rzupqaeb7bbwv6jn658 \
  -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' \

Responses

204 No Content

If your API call succeeds, the specified client will be deleted, and you'll see the response code 204 No Content.

401 Unauthorized

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

404 Not Found

  • Client ID not found or Application ID not found. You did not provide a valid application and/or client ID.

/config/{app}/clients/{client_id}/secret

Description

Client secrets serve as the password for API clients. For example, to call a Janrain REST API you must supply both the client ID (effectively the client "username") and the client secret. Client secrets are meant to be just that: secret. If you believe a client secret has been compromised, you can use the /config/{app_id}/clients/{client_id}/secret endpoint to generate a new client secret. That's a process equivalent to changing your user password.

This endpoint includes the following methods:

  • PUT

URI Parameters

client_id string required

put

Description

Resets the client secret for an API client. The client secret, for our purposes, is the password for the API client. As such, the secret should be reset if you believe it has been exposed to unauthorized users, if a user who had access to the secret has left your organization, and so on.

When resetting a client secret, the request body of your API call must include the hoursToLive property. When you reset a client secret, the new secret takes effect immediately; at the same time, you can allow the old secret to remain in effect for as long as one week (168 hours). (That means that, for the specified amount of time, the API client will have two valid secrets: the old secret and the new secret.) The specified amount of time is dictated by the hoursToLive property, which can be set to any integer value between 0 hours and 168 hours, inclusive. Setting hoursToLive to 0 causes the old secret to expire as soon as the new secret takes effect.

Your API call must have the owner permission in order to reset a client secret.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID, and replace nmub5w3rru9k6rzupqaeb7bbwv6jn658 with your client ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/nmub5w3rru9k6rzupqaeb7bbwv6jn658/secret

Sample Request (curl)

This command resets the client secret for the API client with the client ID nmub5w3rru9k6rzupqaeb7bbwv6jn658. In addition, it sets the hoursToLive property to 4 hours:

curl -X PUT \
   https://api.datateam.dev.or.janrain.com/config/73jzx34tnr5ruhsze494ssgz2b/clients/3bchk5hsx6v58dkn288nbybmxfyk32u7/secret \
  -H 'Authorization: Basic YjhkcmRqNDZ0Z3o3ZTNmcWZiZms2M2JxenVucXpmbmo6a3Nud3pudjlweWZqYWtnOXF0a3hiNXJ6bTV6eGhuNDY=' \
  -H 'Content-Type: application/json' \
  -d '{    
          "hoursToLive": "4"
      }
'

Responses

200 OK

If the client secret is successfully reset, the new secret will be displayed onscreen:

{
  "secret": "dfetkpa9g4xecc9t5es33x8r374t0pol"
}

400 Bad Request

  • Missing data for required field. You failed to include the hoursToLive property.
  • Must be between 0 and 168. The hoursToLive property must be set to an integer value between 0 and 168, inclusive.

401 Unauthorized

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

404 Not Found

  • Client ID not found or Application ID not found. You did not provide a valid application and/or client ID.

/config/{app}/clients/{client_id}/settings

Description

API clients serve two major purposes: they make authenticated requests against the Janrain REST APIs, and they (or, more specifically, API clients that have the login_client feature set) authenticate users during logon and registration. Each client also has a collection of settings that help govern activities under the client's control. For example, the login_attempts setting specifies how many times a user can attempt to log on before his or her account is temporarily locked out.

The /config/{app_id}/clients/{client_id}/settings endpoint enables you to return settings information for a specific API client. In addition, the PUT method enables you to modify client settings.

This endpoint includes the following methods:

  • GET
  • PUT

URI Parameters

client_id string required

get

Description

Returns the settings associated with a specific API client. The endpoint returns the following information for the specified client:

  • Janrain client settings configured specifically for the client itself.
  • Janrain settings configured at the global level.
  • Custom settings defined for the client. Custom settings are defined as any setting not included in the Janrain client settings.

As a general rule, global settings apply to all API clients. However, if the client has its own version of the setting the client version applies. For example, suppose the global settings show this:

login_attempts = 7  

Let’s further suppose that the API client includes this setting:

login_attempts = 4

In this case, anyone logging on using the API client will be allowed
a maximum of 4 logon attempts before their logon privileges are temporarily suspended. That's because the API client setting (the local setting) overrides the global setting.


Note, however, that there are some settings that can only be configured at the global scope. For example, if you configure {entity_type}_distinguisher_field at the individual client level that setting will be ignored. That's because {entity_type}_distinguisher_field is only valid when configured at the global scope.

Client settings, global settings, and custom settings are returned as separate JSON objects.

To return settings information for a specified API client, your API call must run with either owner credentials or with the API credentials of the client in question.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID, and replace xyv3q7xhces2yy7cumgrte24epx4m2st with your client ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xyv3q7xhces2yy7cumgrte24epx4m2st/settings

Sample Request (curl)

This command returns settings information for the API client with the client ID nhjsdtjwvaytevc2w5sx42skggvjn7bu:

curl -X GET \
https://v1.api.us.janrain.com/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu/settings

Responses

200 OK

If your call to this endpoint succeeds, you'll get back settings information for the specified API client similar to this:

{
    "_global": {
        "_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\" <noreply@janrain.com>",
        "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"
    },
    "_self": "/config/73jzx34tnr5ruhsze494ssgz2b/clients/nhjsdtjwvaytevc2w5sx42skggvjn7bu/settings",
    "custom": {},
    "default_flow_name": "standard",
    "default_flow_version": "20170915215708415365",
    "email_method": "ses_sync",
    "email_sender_address": "\"Janrain Console\" <noreply@janrain.com>",
    "rpx_app_id": "kbcpdniaklcfajlapmif",
    "rpx_key": "69a70c57f856dcb7a28f672fc0c8e8556c1e3672",
    "rpx_realm": "capture",
    "site_name": "New Test Site"
}

401 Unauthorized

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

404 Not Found

  • Client ID not found or Application ID not found. You did not provide a valid application and/or client ID.

put

Description

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:

  • API client; this endpoint cannot modify the global client settings. For example, suppose you have login_attempts defined in both the global settings and in the client settings for API Client A. You can use this endpoint to remove login_attempts from Client A. When you do so, however, the login_attempts setting in the global settings will not be deleted.
  • You must specify all the settings for a client in the response 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 this 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; and recover_code_lifetime. Let's further suppose that your request body updates the only login_attempts and 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": "3600",
  "verification_code_lifetime": "3600",
  "_global": {
      "rpx_realm": "greg-stemp",
      "user_search_query_fields": "[\"created\", \"displayName\", \"email\", \"lastUpdated\", \"uuid\"]",
      "user_distinguisher_field": "primaryAddress.country",
      "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 and then, within that 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": "2400",
  "verification_code_lifetime": "2400",
}

Note that the first three settings – site_name, login_attempts_threshold, and login_attempts – remain in the request body even though no changes were made to them. Do not remove these settings from the request body. If you do, they will also be deleted from the API client settings.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID, and replace xyv3q7xhces2yy7cumgrte24epx4m2st with your client ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xyv3q7xhces2yy7cumgrte24epx4m2st/settings

Sample Request (curl)

This command updates the site_name setting for the API client with the client ID xyv3q7xhces2yy7cumgrte24epx4m2st:

curl -X PUT \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients/xyv3q7xhces2yy7cumgrte24epx4m2st/settings \
  -H 'Content-Type: application/json' \
  -d '{
    "site_name":"Documentation Test Site"
      }
'

Responses

200 OK

If your API call succeeds, you should get back the updated property values for the API client. For example:

{
    "_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\" <noreply@janrain.com>",
    "rpx_app_id": "kbcpdniaklcfajlapmif",
    "rpx_key": "69a70c57f856dcb7a28f672fc0c8e8556c1e3672",
    "rpx_realm": "capture",
    "site_name": "Documentation Test Site"
}

400 Bad Request

  • 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.
  • Setting key is not a valid string. Make sure you have enclosed your string values in double quotes.
  • Setting key must be a boolean value. The specified setting
    can only be set to true or false.
  • Setting key must be valid json. The specified key must use the JSON syntax.
  • Setting key must be an integer. The specified key only accepts integer values.
  • 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.

401 Unauthorized

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

404 Not Found

Client ID not found orApplication ID not found. You did not provide a valid application and/or client ID.

/config/{app}/entityTypes

Description

Entity types refer to the schemas that underlie user profile databases; in the Janrain Console, you can find the names of all your entity types by expanding the Manage Schemas link.

The /config/{app_id}/entityTypes endpoint returns information about all the entity types associated with an application. In addition to that, you can use the POST method of this endpoint to create a new entity type.

The /config/{app_id}/entityTypes endpoint includes the following methods:

  • GET

get

Description

Returns information about all the entity types associated with an application.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes

Sample Request (curl)

This command returns information about all the entity types associated with the application htb8fuhxnf8e38jrzub3c7pfrr.

curl -X GET \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes \
  -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' 

Responses

200 OK

If your API call succeeds, you'll get back information similar to this for each of your entity types:

[
    {
        "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/Test",
        "name": "Test"
    },
    {
        "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user",
        "name": "user"
    }
]

401 Unauthorized

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

404 Not Found

  • Application ID not found. You did not provide a valid application ID.

/config/{app}/entityTypes/{entity_type}

Description

Entity types refer to the schemas that underlie user profile databases. The /config/{app_id}/entityTypes/{entity_type} endpoint provides a way to return information about a specific entity type associated with an application.

Note that you cannot use this endpoint to modify an entity type; that is, the endpoint cannot add, delete, or modify the attributes that make up an entity type. To work with attributes, use the /config/{app_id}/entityTypes/{entity_type}/attributes/{attribute_name} endpoint.

This endpoint includes the following methods:

  • GET

URI Parameters

entity_type string required

get

Description

Returns information about the specified entity type.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID and replace test with the name of your entity type:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/test

Sample Request (curl)

This command returns information about the user entity type associated with the application that has the application ID htb8fuhxnf8e38jrzub3c7pfrr:

curl -X GET \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user \
  -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' 

Responses

200 OK

If your API call succeeds you'll get back information about the specified entity type. The information consists of two relative URLS:

  • _self, the URL of the entity type itself.
  • _attributes, the URL used for managing the attributes associated with the entity type.

For example:

{
    "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/test",
    "_attributes": "/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/test/attributes"
}

401 Unauthorized

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

404 Not Found

  • Application ID not found. You did not provide a valid application ID.

/config/{app}/entityTypes/{entity_type}/attributes

Description

Attributes are the individual fields that make up an entity type schema. The /config/{app_id}/entityTypes/{entity_type}/attributes endpoint returns detailed information about each attribute, including the attribute name and datatype.

This endpoint includes the following methods:

  • GET

URI Parameters

entity_type string required

get

Description

Returns information about all the attributes associated with the specified entity type.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID and test with the name of your entity type:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/test/attributes

Sample Request (curl)

This command returns the attributes associated with the user entity type and the application with the application ID htb8fuhxnf8e38jrzub3c7pfrr:

curl -X GET \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user/attributes \
  -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU=' \

Responses

200 OK

If your call to this endpoint succeeds, you'll get back information for each attribute in the specified entity type;for more information about the attribute properties returned by the call, see Viewing Schema Information.

Your returned data will look similar to this:

{
   "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user/attributes",
   "attributes": [
       {
           "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user/attributes/id",
           "required": false,
           "description": "simple identifier for this entity",
           "reverse-query": false,
           "ignore-update": null,
           "query": false,
           "unique": false,
           "case-sensitive": null,
           "name": "id",
           "locally-unique": false,
           "default": null,
           "primary-key": false,
           "length": null,
           "type": "id"
       },
     }
   ]
}

401 Unauthorized

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

404 Not Found

  • Application ID not found. You did not provide a valid application ID.

/config/{app}/entityTypes/{entity_type}/attributes/{name}

Description

Attributes are the individual fields that make up an entity type schema. The /config/{app_id}/entityTypes/{entity_type}/attributes endpoint returns detailed information about a specified attribute, including the attribute name and datatype.

This endpoint includes the following methods:

  • GET

URI Parameters

entity_type string required
name string required

get

Description

Returns information about the specified attribute.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID, replace user with the name of your entity type, and replace displayName with the name of the attribute you want to return information for:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user/attributes/displayName

Sample Request (curl)

This command returns information about the displayName attribute found in the user entity type:

curl -X GET \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user/attributes/displayName

Responses

200 OK

If your call to this endpoint succeeds, you'll get back information similar to this:

{
    "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/entityTypes/user/attributes/displayName",
    "required": false
    "description": "The name of this Contact, suitable for display to end-users.",
    "reverse-query": false,
    "ignore-update": null,
    "query": true,
    "unique": false,
    "case-sensitive": false,
    "name": "displayName",
    "locally-unique": false,    
    "default": null,
    "primary-key": false,
    "length": 1000,
    "type": "string"
}

401 Unauthorized

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

404 Not Found

  • Application ID not found. You did not provide a valid application ID.

/config/{app}/flows

get

Description

Returns a list of flows.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/standard",
    "name": "standard"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow",
    "name": "myCoolFlow"
  }
]

404 Not Found

Capture application could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Capture application not found."
}

/config/{app}/flows/{flow}

URI Parameters

flow string required

The flow name.

get

Description

Returns the current version of the flow.

Responses

200 OK

Response Example (application/json)
{
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow",
  "name": "myCoolFlow",
  "version": "2015111701280483247",
  "userData": [
      "email",
      "displayName",
      "givenName"
  ],
  "schemas": [
      "myCoolEntityType"
  ]
}

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

put

Description

Updates/replaces userData object and/or entityTypes in the flow. userData lists the schema attributes to store in the janrainCaptureProfileData object in Local Storage for a logged-in user.

Security

Request Example (application/json)

{
  "userData": [
    "email",
    "displayName",
    "familyName",
    "primaryAddress.country"
  ],
  "schemas": [
    "myCoolEntityType"
  ]
}

Responses

204 No Content

Successfully updated the Flow.

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

409 Conflict

The requested Flow is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/copy

post

Description

Creates a new flow by copying an existing flow. The name attribute in the request specifies the name of the new flow. This endpoint cannot be used to overwrite an existing flow.

Security

Request Example (application/json)

{
  "name": "myCoolFlow"
}

Responses

201 Created

Successfully created a new flow.

Response Headers

Location string

The location of the newly-created flow.

Example: Location: /config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow
Response Example (application/json)
{
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow",
  "name": "myCoolFlow",
  "version": "2015111705580676795"
}

404 Not Found

Capture application could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Capture application not found."
}

/config/{app}/flows/{flow}/fields

get

Description

Returns a list of fields defined in the flow.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/signInEmailAddress",
    "name": "signInEmailAddress"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/currentPassword",
    "name": "currentPassword"
  }
]

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

post

Description

Adds a field to the flow. The schemaAttribute must be a dot-separated path to an existing schema attribute. Call the schemas endpoint for a list of valid attributes.

Security

Request Example (application/json)

{
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.displayName",
  "placeholder": {
    "key": "6e15067b-2ca5-43c3-af96-930766d63375"
  },
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },
    {
      "rule": "unique",
      "value": true,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Responses

201 Created

Successfully created a new field.

Response Headers

Location string

The location of the newly-created field.

Example: Location: /config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/myField

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

/config/{app}/flows/{flow}/fields/{field}

URI Parameters

field string required

The field name.

get

Description

Returns a field definition from the flow. Includes validations.

Security

Query Parameters

locale string

If supplied, the field will be translated into the specified locale before being returned. The response will be identical to calling /config/{app}/f lows/{flow}/locales/{locale}/fields/{field}

Responses

200 OK

Response Example (application/json)
{
  "_relationships": {
    "forms": [
      {
        "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/forms/editProfileForm",
        "name": "editProfileForm"
      }
    ]
  },
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/myCustomTextField",
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/b6ced670-7140-4446-9839-da3474860b1a",
    "key": "b6ced670-7140-4446-9839-da3474860b1a",
    "path": "fields.displayName.label",
    "values": {
      "en-US": "Display Name"
    }
  },
  "tip": {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/8b93448a-6f00-448c-952b-0f1536107cf7",
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7",
    "path": "fields.displayName.tip",
    "values": {
      "en-US": ""
    }
  },
  "socialProfileData": "profile.displayName",
  "placeholder": {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/6e15067b-2ca5-43c3-af96-930766d63375",
    "key": "6e15067b-2ca5-43c3-af96-930766d63375",
    "path": "fields.displayName.placeholder",
    "values": {
      "en-US": "Display Name"
    }
  },
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/bb2b21a1-98df-4dce-84f7-534013c46225",
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225",
        "path": "fields.displayName.validation.messages.required",
        "values": {
          "en-US": "Display name is required."
        }
      }
    },
    {
      "rule": "unique",
      "value": true,
      "message": {
        "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/63f7c18f-521a-4b4f-94c4-0b04b870c82e",
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e",
        "path": "fields.displayName.validation.messages.unique",
        "values": {
          "en-US": "That display name is already taken."
        }
      }
    }
  ]
}

404 Not Found

Field could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Field not found."
}

put

Description

Updates/replaces a field in the flow.

Security

Request Example (application/json)

{
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.displayName",
  "placeholder": {
    "key": "6e15067b-2ca5-43c3-af96-930766d63375"
  },
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },
    {
      "rule": "unique",
      "value": true,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Responses

204 No Content

Successfully updated the Field.

404 Not Found

Field could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Field not found."
}

409 Conflict

The requested Field is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

delete

Description

Removes a field from the flow. Also removes the field from any forms that were using it.

Security

Query Parameters

force string

Forces the deletion of a field even if it's still being used in forms. Forms in question will have the field removed.

Possible values:
  • true
  • false

Responses

204 No Content

Successfully deleted the Field.

404 Not Found

Field could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Field not found."
}

409 Conflict

The requested Field is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/forms

get

Description

Returns a list of forms in the flow.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/forms/signInForm",
    "name": "signInForm"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/forms/editProfileForm",
    "name": "editProfileForm"
  }
]

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

/config/{app}/flows/{flow}/forms/{form}

URI Parameters

form string required

The form name.

get

Description

Returns a list of fields in a form.

Security

Responses

200 OK

Response Example (application/json)
{
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/forms/signInForm",
  "fields": [
    {
      "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/signInEmailAddress",
      "name": "signInEmailAddress",
      "required": false
    },
    {
      "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/currentPassword",
      "name": "currentPassword",
      "required": false
    }
  ]
}

404 Not Found

Form could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Form not found."
}

put

Description

Updates/replaces the list of fields and features in the form. Any fields added to the form must already exist in the flow.

Security

Request Example (application/json)

{
  "fields": [
    {
      "name": "signInEmailAddress"
    },
    {
      "name": "currentPassword"
    }
  ]
}

Responses

204 No Content

Successfully updated the Form.

404 Not Found

Form could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Form not found."
}

409 Conflict

The requested Form is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/locales

get

Description

Returns a list of locales that are available.

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US",
    "name": "en-US"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/it-IT",
    "name": "it-IT"
  }
]

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

/config/{app}/flows/{flow}/locales/{locale}

URI Parameters

locale string required

get

Description

Returns the translation values for a locale.

Responses

200 OK

Response Example (application/json)
{
    "1ab1f15d-2555-49af-bd88-cf984ad40a13": "Come se scrive?",
    "a8670648-f9f7-4c0b-92cd-e477fe67b617": "Come se dice.",
    "991a5781-cbe1-4770-bbf1-395168a11d59": "Olio di gomito."
}

404 Not Found

Locale could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Locale not found."
}

/config/{app}/flows/{flow}/locales/{locale}/fields

get

Description

Returns a list of fields defined in the flow. Alias of /config/{app}/flows/{flow}/fields.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US/fields/signInEmailAddress",
    "name": "signInEmailAddress"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US/fields/currentPassword",
    "name": "currentPassword"
  }
]

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

post

Description

Adds a field to the flow. Works just like /config/{app}/flows/{flow}/fields/{field} except translatable values are accepted in the locale specified. The schemaAttribute must be a dot- separated path to an existing schema attribute. Call the schemas endpoint for a list of valid attributes.

Security

Request Example (application/json)

{
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": "foo",
  "tip": "foo",
  "socialProfileData": "profile.displayName",
  "placeholder": "foo",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": "foo"
    },
    {
      "rule": "unique",
      "value": true,
      "message": "foo"
    }
  ]
}

Responses

201 Created

Successfully created a new field.

Response Headers

Location string

The location of the newly-created field.

Example: Location: /config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/myField

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

/config/{app}/flows/{flow}/locales/{locale}/fields/{field}

URI Parameters

field string required

get

Description

Returns a field definition from the flow translated into the locale specified. Includes validations.

Security

Responses

200 OK

Response Example (application/json)
{
  "_relationships": {
    "forms": [
      {
        "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/forms/editProfileForm",
        "name": "editProfileForm"
      }
    ]
  },
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/fields/myCustomTextField",
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": "foo",
  "tip": "foo",
  "socialProfileData": "profile.displayName",
  "placeholder": "foo",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": "foo"
    },
    {
      "rule": "unique",
      "value": true,
      "message": "foo"
    }
  ]
}

404 Not Found

Field could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Field not found."
}

put

Description

Updates/replaces a field in the flow.

Security

Request Example (application/json)

{
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": "foo",
  "tip": "foo",
  "socialProfileData": "profile.displayName",
  "placeholder": "foo",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": "foo"
    },
    {
      "rule": "unique",
      "value": true,
      "message": "foo"
    }
  ]
}

Responses

204 No Content

Successfully updated the Field.

404 Not Found

Field could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Field not found."
}

409 Conflict

The requested Field is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/locales/{locale}/mailTemplates

get

Description

Returns a list of all email templates in the specified locale.

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US/mailTemplates/reactivateAccount",
    "name": "reactivateAccount"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US/mailTemplates/passwordRecover",
    "name": "passwordRecover"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US/mailTemplates/registrationVerification",
    "name": "registrationVerification"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US/mailTemplates/emailAddressChanged",
    "name": "emailAddressChanged"
  }
]

/config/{app}/flows/{flow}/locales/{locale}/mailTemplates/{template}

URI Parameters

template string required

get

Description

Returns a single email template in the specified locale.

Responses

200 OK

Response Example (application/json)
{
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/locales/en-US/mailTemplates/registrationVerification",
  "name": "registrationVerification",
  "subject": "Verify your email",
  "textBody": "Welcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.\n\n{*&email_verification_url*}\n",
  "htmlBody": "<p>\nWelcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.\n</p>\n<p>\n<a href=\"{*email_verification_url*}\">{*email_verification_url*}</a>\n</p>\n"
}

put

Description

Update a single email template in the specified locale.

Request Example (application/json)

{
  "subject": "Verify your email",
  "textBody": "Welcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.\n\n{*&email_verification_url*}\n",
  "htmlBody": "<p>\nWelcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.\n</p>\n<p>\n<a href=\"{*email_verification_url*}\">{*email_verification_url*}</a>\n</p>\n"
}

Responses

204 No Content

Successfully updated the email template.

409 Conflict

The requested email template is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/locales/{locale}/mailTemplates/{template}/body

get

Description

Returns the body for this email template in the specified locale. The Accept header determines whether the text or html version is returned.

Request Headers

Accept string required

Specify the format to return.

Possible values:
  • text/plain
  • text/html

Responses

200 OK

Response Example (text/plain)
Welcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.

{*&email_verification_url*}
Response Example (text/html)
<p>
Welcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.
</p>
<p>
<a href=\"{*email_verification_url*}\">{*email_verification_url*}</a>
</p>

406 Not Acceptable

A GET request was made with an Accept header, or a PUT/POST request was made with a Content-Type header, that is invalid. Refer to the headers section of this method to see what types are acceptable.

Response Example (application/json)
{
  "errors": {
    "received": "application/json",
    "accepts": [
      "text/html",
      "text/plain"
    ]
  }
}

put

Description

Update the body for this email template in the specified locale. The Content-Type header determines whether the text or html version is updated.

Request Headers

Content-Type string required

Specify the format to modify.

Possible values:
  • text/plain
  • text/html

Request Example (text/plain)

Welcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.

{*&email_verification_url*}

Request Example (text/html)

<p>
Welcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&displayName*}{*/user*}! To complete your new registration, just click on or browse to the URL below to verify this email address.
</p>
<p>
<a href=\"{*email_verification_url*}\">{*email_verification_url*}</a>
</p>

Responses

204 No Content

Successfully updated the subject.

406 Not Acceptable

A GET request was made with an Accept header, or a PUT/POST request was made with a Content-Type header, that is invalid. Refer to the headers section of this method to see what types are acceptable.

Response Example (application/json)
{
  "errors": {
    "received": "application/json",
    "accepts": [
      "text/html",
      "text/plain"
    ]
  }
}

/config/{app}/flows/{flow}/locales/{locale}/mailTemplates/{template}/subject

get

Description

Returns the subject for this email template in the specified locale.

Request Headers

Accept string required
Possible values:
  • text/plain

Responses

200 OK

Response Example (text/plain)
Verify your email

406 Not Acceptable

A GET request was made with an Accept header, or a PUT/POST request was made with a Content-Type header, that is invalid. Refer to the headers section of this method to see what types are acceptable.

Response Example (application/json)
{
  "errors": {
    "received": "application/json",
    "accepts": [
      "text/html",
      "text/plain"
    ]
  }
}

put

Description

Update the subject for this email template in the specified locale.

Request Headers

Content-Type string required
Possible values:
  • text/plain

Request Example (text/plain)

Verify your email

Responses

204 No Content

Successfully updated the subject.

406 Not Acceptable

A GET request was made with an Accept header, or a PUT/POST request was made with a Content-Type header, that is invalid. Refer to the headers section of this method to see what types are acceptable.

Response Example (application/json)
{
  "errors": {
    "received": "application/json",
    "accepts": [
      "text/html",
      "text/plain"
    ]
  }
}

/config/{app}/flows/{flow}/locales/{locale}/strings

get

Description

Returns a list of Strings defined in the flow.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/locales/en-US/strings/emailAddressData",
    "name": "emailAddressData"
  },
  {
    "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/locales/en-US/strings/poweredByJanrain",
    "name": "poweredByJanrain"
  }
]

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

post

Description

Adds a String to the flow.

Security

Request Example (application/json)

{
  "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/locales/en-US/strings/poweredByJanrain",
  "name": "poweredByJanrain",
  "value": "Powered by Janrain"
}

Responses

201 Created

Successfully created a new String.

Response Headers

Location string

The location of the newly-created String.

Example: Location: /config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/strings/poweredByJanrain

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

/config/{app}/flows/{flow}/locales/{locale}/strings/{string}

URI Parameters

string string required

get

Description

Returns a String definition from the flow.

Security

Responses

200 OK

Response Example (application/json)
{
  "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/locales/en-US/strings/poweredByJanrain",
  "name": "poweredByJanrain",
  "value": "Powered by Janrain"
}

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

put

Description

Updates/replaces a string in the flow.

Security

Request Example (application/json)

{
  "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/locales/en-US/strings/poweredByJanrain",
  "name": "poweredByJanrain",
  "value": "Powered by Janrain"
}

Responses

204 No Content

Successfully updated the String.

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

409 Conflict

The requested String is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

delete

Description

Removes a String from the flow.

Security

Responses

204 No Content

Successfully deleted the String.

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

409 Conflict

The requested String is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/promote

post

Description

Promotes a flow to another app. The app_id and credentials must be specified in the request body. The flow name remains the same. If the other app has a flow with the same name, it will be overwritten.

Security

Request Example (application/json)

{
  "app_id": "someotherappid12345678",
  "client_id": "someotherclientid1234568",
  "client_secret": "someotherclientsecret12345678"
}

Responses

201 Created

Successfully created a new flow.

Response Headers

Location string

The location of the newly-created flow.

Example: Location: /config/someotherappid12345678/flows/myCoolFlow
Response Example (application/json)
{
  "_self": "/config/someotherappid12345678/flows/myCoolFlow",
  "name": "myCoolFlow",
  "version": "2015111705580676795"
}

404 Not Found

Capture application could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Capture application not found."
}

/config/{app}/flows/{flow}/screens

get

Description

Returns a dictionary of all screens for a flow.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/screens/traditionalAuthenticateMerge",
    "name": "traditionalAuthenticateMerge"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/screens/reactivateAccountSuccess",
    "name": "reactivateAccountSuccess"
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/screens/signIn",
    "name": "signIn"
  }
]

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

/config/{app}/flows/{flow}/screens/{screen}

URI Parameters

screen string required

The screen name.

get

Description

Returns a list of information for a specific screen in a flow.

Security

Responses

200 OK

Response Example (application/json)
{
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/screens/signIn",
  "modal": true,
  "name": "signIn"
}

404 Not Found

Screen could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Screen not found."
}

put

Description

Updates the modal value for a screen in a flow. Requires 'modal' value as True/False and 'name' of a valid screen name. '_self' path is optional.

Security

Request Example (application/json)

{
  "modal": false,
  "name": "signIn"
}

Responses

204 No Content

Successfully updated the Screen.

404 Not Found

Screen could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Screen not found."
}

409 Conflict

The requested Screen is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/strings

get

Description

Returns a list of Strings defined in the flow.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/emailAddressData",
    "name": "emailAddressData"
  },
  {
    "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/poweredByJanrain",
    "name": "poweredByJanrain"
  }
]

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

post

Description

Adds a String to the flow.
Strings must contain either schemaId or value. Do not provide both.

Security

Request Example (application/json)

{
  "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/myCoolString",
  "name": "myCoolString",
  "schemaId": "myCoolAttribute",
  "value": {
    "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/myCoolString",
    "key": "a0861174cd5d46eb65d38ee3ec137d55",
    "path": "strings.myCoolString.value",
    "values": {
      "en-US": "This is a cool string"
    }
  }
}

Responses

201 Created

Successfully created a new string.

Response Headers

Location string

The location of the newly-created string.

Example: Location: /config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/strings/myCoolString

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

/config/{app}/flows/{flow}/strings/{string}

URI Parameters

string string required

get

Description

Returns a String definition from the flow.

Security

Responses

200 OK

Response Example (application/json)
{
  "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/myCoolString",
  "name": "myCoolString",
  "schemaId": "myCoolAttribute",
  "value": {
    "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/myCoolString",
    "key": "a0861174cd5d46eb65d38ee3ec137d55",
    "path": "strings.myCoolString.value",
    "values": {
      "en-US": "This is a cool string"
    }
  }
}

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

put

Description

Updates/replaces a string in the flow.
Strings must contain either schemaId or value. Do not provide both.

Security

Request Example (application/json)

{
  "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/myCoolString",
  "name": "myCoolString",
  "schemaId": "myCoolAttribute",
  "value": {
    "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/strings/myCoolString",
    "key": "a0861174cd5d46eb65d38ee3ec137d55",
    "path": "strings.myCoolString.value",
    "values": {
      "en-US": "This is a cool string"
    }
  }
}

Responses

204 No Content

Successfully updated the String.

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

409 Conflict

The requested String is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

delete

Description

Removes a String from the flow.

Security

Responses

204 No Content

Successfully deleted the String.

404 Not Found

String could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "String not found."
}

409 Conflict

The requested String is currently in use and cannot be updated. Please try again later.

Response Example (application/json)
{
  "errors": "Resource currenty locked. Please try again later."
}

/config/{app}/flows/{flow}/translations

get

Description

Returns a dictionary of all translations.

Request Headers

Accept string

Specify the format to return.

Possible values:
  • application/json
  • text/csv

Responses

200 OK

Response Example (application/json)
[
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/991a5781-cbe1-4770-bbf1-395168a11d59",
    "key": "991a5781-cbe1-4770-bbf1-395168a11d59",
    "path": "fields.someField.label",
    "values": {
      "en-US": "Register",
      "fr-FR": "Faire inscrire",
      "it-IT": "Registrati"
    }
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/1ab1f15d-2555-49af-bd88-cf984ad40a13",
    "key": "1ab1f15d-2555-49af-bd88-cf984ad40a13",
    "path": "fields.anotherField.label",
    "values": {
      "en-US": "Hello!",
      "fr-FR": "Bonjour!",
      "it-IT": "Bongiorno!"
    }
  },
  {
    "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/a8670648-f9f7-4c0b-92cd-e477fe67b617",
    "key": "a8670648-f9f7-4c0b-92cd-e477fe67b617",
    "path": "fields.oneMoreField.label",
    "values": {
      "en-US": "Goodbye!",
      "fr-FR": "Au revoir!",
      "it-IT": "Arrivederci!"
    }
  }
]
Response Example (text/csv)
path,key,en-US,it-IT,fr-FR
fields.someField.label,991a5781-cbe1-4770-bbf1-395168a11d59,Register,Registrati,Faire inscrire
fields.anotherField.label,1ab1f15d-2555-49af-bd88-cf984ad40a13,Hello!,Bongiorno!,Bonjour!
fields.oneMoreField.label,a8670648-f9f7-4c0b-92cd-e477fe67b617,Goodbye,Arrivederci!,Au revoir!

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

patch

Description

Updates existing translations. This endpoint does not delete data.

Request Example (application/json)

[
  {
    "key": "a8670648-f9f7-4c0b-92cd-e477fe67b617",
    "values": {
      "en-US": "See ya!"
    }
  }
]

Request Example (text/csv)

key,en-US
a8670648-f9f7-4c0b-92cd-e477fe67b617,See ya!

Responses

204 No Content

Successfully updated the translations.

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

post

Description

Adds new translation strings to the translations dictionary. You must supply a list of values for each locale defined in the flow. For a list of locales, call /config/{app}/flows/{flow}/locales.

Request Example (application/json)

[
  {
    "values": {
      "en-US": "Hello!",
      "fr-FR": "Bonjour!",
      "it-IT": "Bongiorno!"
    }
  },
  {
    "values": {
      "en-US": "Goodbye!",
      "fr-FR": "Au revoir!",
      "it-IT": "Arrivederci!"
    }
  }
]

Request Example (text/csv)

en-US,it-IT
Hello!,Bongiorno!
Goodbye,Arrivederci!

Responses

201 Created

Returns a partial rendering of the affected locales.

Response Headers

Content-Location string

The location of the full translation dictionaries.

Example: Content-Location: /config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations
Response Example (application/json)
{
  "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/translations",
  "translations": [
    {
      "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/translations/5ac7ea6d-48b8-46d5-abed-ac3b6b12268f",
      "path": "",
      "values": {
        "it-IT": "Arrivederci!",
        "en-US": "Goodbye!",
        "fr-FR": "Au revoir!"
      },
      "key": "5ac7ea6d-48b8-46d5-abed-ac3b6b12268f"
    },
    {
      "_self": "/config/4qeam8586cpkuru3ju8kj2xwdf/flows/myCoolFlow/translations/6bdb687e-3d9f-4018-be6b-613011ad8b70",
      "path": "",
      "values": {
        "it-IT": "Bongiorno!",
        "en-US": "Hello!",
        "fr-FR": "Bonjour!"
      },
      "key": "6bdb687e-3d9f-4018-be6b-613011ad8b70"
    }
  ]
}

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

/config/{app}/flows/{flow}/translations/{key}

URI Parameters

key string required

get

Description

Returns a dictionary of all translations for a key.

Responses

200 OK

Response Example (application/json)
{
  "_self": "/config/v86cchggr5cdvbfh7ydk8s63zz/flows/myCoolFlow/translations/991a5781-cbe1-4770-bbf1-395168a11d59",
  "key": "991a5781-cbe1-4770-bbf1-395168a11d59",
  "path": "",
  "values": {
    "en-US": "Elbow grease.",
    "it-IT": "Olio di gomito."
  }
}

404 Not Found

Translation string could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Translation string not found."
}

delete

Description

Deletes a translation string if it is not in use.

Responses

204 No Content

Successfully deleted the Translation string.

404 Not Found

Translation string could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Translation string not found."
}

409 Conflict

The request could not be completed because the string is in use.

Response Example (application/json)
{
  "errors": "Cannot delete a translation key that is still in use"
}

/config/{app}/flows/{flow}/versions

get

Description

Returns a list of all versions for a particular flow, along with a change note for each version.

Security

Responses

200 OK

Response Example (application/json)
[
  {
    "change": "Updated field: givenName",
    "version": "HEAD"
  },
  {
    "change": "Updated field: givenName",
    "version": "201601201956110829464"
  },
  {
    "change": "Updated field: firstName",
    "version": "201601201954520534731"
  },
  {
    "change": "Created.",
    "version": "201601201954370741786"
  }
]

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow not found."
}

/config/{app}/flows/{flow}/versions/{version}

URI Parameters

version string required

get

Description

Returns the version of the flow.

Security

Responses

200 OK

Response Example (application/json)
{
    "authProfileData": [
        "name",
        "verifiedEmail",
        "identifier"
    ],

    "...shortened...": "...for brevity...",

    "userData": [
        "email",
        "displayName"
    ],
    "version": "00000000-0000-0000-0000-000000000000"
}

404 Not Found

Flow Version could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow Version not found."
}

post

Description

Restores flow to version

Security

Responses

404 Not Found

Flow Version could not be found. Please check the value and try again.

Response Example (application/json)
{
  "errors": "Flow Version not found."
}

/config/{app}/settings

Description

Each API client has a collection of property settings; these settings are documented on the API Clients and Permissions page. In addition to these client-specific settings, each application has its own collection of settings; these settings (known as the "global settings") can be found in the Janrain Console on the Manage Application page.

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 a maximum of 5 failed login attempts before temporarily locking that user out of the web site.

There is one exception, however. If the same setting is also defined for a client application, then the 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.

The config/{app_id}/settings endpoint provides a way to retrieve the global settings for an application. In addition to that, you can use the PUT method to modify any or all of those settings.

This endpoint includes the following methods:

  • GET
  • PUT

get

Description

Returns settings and values applied at the global scope; in the Janrain Console, these are the settings defined on the Manage Application page. This endpoint returns all the global Janrain client settings as well as any custom settings configured at the global scope. Your API call must have owner permissions in order to return the global settings.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/settings

Sample Request (curl)

The following command returns settings information for the Capture application with the ID htb8fuhxnf8e38jrzub3c7pfrr:

curl -X GET \
https://v1.api.us.janrain.com/config/73jzx34tnr5ruhsze494ssgz2b/settings \
 -H 'Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6eXk4MmhxdXhnbWt6bWMzcGRoZ3VmdDNwNHluc3R6cjU='

Query Parameters

include_clients boolean

In addition to the global API client settings, this parameter causes your API call to return settings configured for each individual API client. If not specified, the parameter is set to the default value (false). That means that only the global settings are returned.

For example, suppose your global settings consist of just two values:

  • login_attempts
  • login_attempts_threshold

If your API clients do not include any other settings, the the endpoint returns only those the two global settings. However, suppose Client A includes an additional setting: site_name. In that case, the endpoint returns information for the two global settings and for site_name, the one setting configured at the local scope.

In other words, 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.

Responses

200 OK

If your call to this endpoint succeeds, you'll get back settings information for the specified application. For example:

{
    "_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\" <noreply@janrain.com>",
    "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"
}

401 Unauthorized

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

404 Not Found

  • Application ID not found. You did not provide a valid application ID.

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 Clients and Permissions page or returned by the /config/{app_id}/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:

{
    "custom": {
   "application_region":"US",
    "is_test_site":"false"
      },
   "email_method": "ses_sync"
}

Any standard client settings (e.g., email_method) are then defined after the custom property.

Keep in mind that any global settings not defined in the body parameter are 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\" 
<noreply@janrain.com>"

Suppose you now make an API call that has the following body parameter value:

{
    "email_sender_address": "admin@janrain.com"
}

That command changes the email_sender_address property. However, it will deletes the email_method property; that's because that property was not included in the API call. As a result, your global settings will contain just one property:

"email_sender_address": admin@janrain.com"

Security

  • Basic Authentication

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID:

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 \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/settings \
  -H 'Content-Type: application/json' \
  -d '{{
    "custom": {
        "site_locale":"US"
    },
    "email_method": "ses_sync",
    "email_sender_address": "\"Janrain Console\" <noreply@janrain.com>"
}
'

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": "\"Janrain Console\" <noreply@janrain.com>",
}

400 Bad Request

  • Setting key is not a valid string. This typically occurs if you use a blank space anywhere in the setting name.
  • Setting key must be a boolean value.Indicates that the setting only accepts true/false values.
  • Setting key must be valid json. Indicates that the setting only accepts JSON values.
  • Setting key must be an integer. Indicates that the setting only accepts integer values.
  • Value is supplied that does not pass additional validation rules defined for the specified key. Verify the validation rules for the setting and try the API call again.

401 Unauthorized

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

404 Not Found

  • Application ID not found. You did not provide a valid application ID.

/config/{app}/settings/options

Description

Each API client has a collection of property settings; the currently-configured property settings for an API client can be found in the Janrain Console in the Manage Properties section.

However, it's unlikely that any one client has all the possible client settings configured; more typically, a client will have a relatively small number of configured settings. So how do you know Which settings might be available to you? One way is to check the API Clients and Permissions page.

However, another approach is to use the /config/{app_id}/settings/options endpoint. That endpoint returns information similar to this for each available setting:

"globalOnly": true,
"group": "Customer Care Portal",
"name": "invitation_search_allow_empty",
        "type": "boolean",
        "values": [
            true,
          false
          ]

The returned data includes the following properties:

  • globalOnly. When set to true, indicates that the setting can only be configured at the global scope, and cannot be configured for individual API clients. (If you try to configure the setting at the client scope that key will be ignored.)
  • group. General group that the setting belongs to. Groups include: Backplane; Customer Care Portal; Social Login; Transactional Emails; and General Settings.
  • name. Name of the setting. Site names are case sensitive. For example, you cannot type site_name as Site_Name. If you do, that incorrect setting will be ignored.
  • type. Datatype for the setting.
  • values. Allowed values for the setting; for example, {entity_type}_search_allow_empty can only be set to true or false. If you see the following syntax, that means that there is not a predefined set of values for the setting: "values": [].

This endpoint includes the following methods:

  • GET

get

Description

Returns information about available client settings. These settings are summarized on the API Clients and Permissions page.

Sample Request URL

In the following URL, replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/settings/options

Sample Request (curl)

The following command returns custom setting information for the application htb8fuhxnf8e38jrzub3c7pfrr.

curl -X GET \
https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/settings/options

Responses

200 OK

If your call to this endpoint succeeds, you'll get back information on the client settings available for the specified application. For example:

[
    {
        "globalOnly": true, 
        "group": "Backplane", 
        "name": "backplane_bus", 
        "type": "string", 
        "values": []
    }, 
    {
        "globalOnly": true, 
        "group": "Backplane", 
        "name": "backplane_password", 
        "type": "string", 
        "values": []
    }, 
    {
        "globalOnly": true, 
        "group": "Backplane", 
        "name": "backplane_server", 
        "type": "string", 
        "values": [
            "backplane1.janrainbackplane.com"
        ]
    }
]

401 Unauthorized

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

404 Not Found

  • Application ID not found. You did not provide a valid application ID.