Identity Cloud: Legacy Clients and Settings API v2

A legacy API to manage API clients and applications for Identity Cloud.

Learn more:


Overview

The Legacy Clients and Settings API can be used to manage API clients and applications. As the word “legacy” implies, however, this API no longer represents the preferred way to programmatically manage API clients and applications. Instead, we recommend you use the Clients and Settings API for those purposes. The legacy API is still supported and the endpoints still work. However, the new API is easier to use, and adheres better to the standard REST API syntax and approach.

If you decide (perhaps for backwards compatibility reasons) to use the Legacy Clients and Settings API, that API offers the endpoints detailed below.

The /clients endpoints

The /clients endpoints are used for creating, deleting, and editing Registration clients. A client has access to the API (and, if applicable) the UI. Default clients have no permissions, so you need to configure them in the Social Login Dashboard unless you add permissions using the features parameter.

A /clients call can only be made by the owner client, denoted by the owner icon in the Dashboard. These endpoints are also used to reset client secrets.

  • /clients/add
  • /clients/clear_whitelist
  • /clients/delete
  • /clients/list
  • /clients/reset_secret
  • /clients/set_description
  • /clients/set_features
  • /clients/set_whitelist

The /settings endpoints

The /settings endpoints are used to make changes to your Registration Dashboard settings. You can change your own settings or use the from_client_id parameter to change another user’s settings. You need to have owner permission to make changes to any account that is not your own. See individual endpoints for call examples and different use cases.

  • /settings/delete
  • /settings/delete_default
  • /settings/get
  • /settings/get_default
  • /settings/get_multi
  • /settings/items
  • /settings/keys
  • /settings/set
  • /settings/set_default
  • /settings/set_multi
  • /settings/widget/delete
  • /settings/widget/get
  • /settings/widget/list
  • /settings/widget/publish

Accessing the Legacy Clients and Settings endpoints

The Legacy Clients and Settings API uses the following endpoint syntax:

https://{app}.janraincapture.com/{endpoint}

To access your API client and setting endpoints, replace {app} with the name of your Capture domain, and replace {endpoint} with the name of the endpoint you want to use. For example:

https://akamai-documentation.us-dev.janraincapture.com/clients/list

Authentication

The Legacy Clients and Settings API requires Basic authentication. To create an authentication string, combine your API client ID, a colon (:), and your client secret into a single value. For example, if your client ID is abcdefg and your client secret is hijklmnop, that value would look like this:

abcdefg:hijklmnop

Next, take the newly created string and base64 encode it. For example, on a Mac, you can base encode the string using this command:

echo -n "abcdefg:hijklmnop" | base64

Or, if you’re running Microsoft Windows, you can encode the string by using a Windows PowerShell command similar to this:

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("abcdefg:hijklmn"))

The resulting value (e.g., YWJjZGVmZzpoaWprbG1ub3A=) should be used in your authentication header.

If you are making API calls using Postman, select Basic Auth as your identification type, then use the client ID as the username and the client secret as the password.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Clients  
Create an API client POST /api/v2/clients/add{?description,features}
Clear an API client whitelist POST /api/v2/clients/clear_whitelist{?for_client_id}
Delete an API client POST /api/v2/clients/delete{?client_id_for_deletion}
List API clients GET /api/v2/clients/list{?has_features}
Reset an API client secret POST /api/v2/clients/reset_secret{?for_client_id,hours_to_live}
Set an API client description POST /api/v2/clients/set_description{?description,for_client_id}
Set API client features POST /api/v2/clients/set_features{?features,for_client_id}
Set an API client whitelist POST /api/v2/clients/set_whitelist{?whitelist,for_client_id}
Settings  
Delete a setting from an API client POST /api/v2/settings/delete{?for_client_id,key}
Remove a key from an application POST /api/v2/settings/delete_default{?key}
Get a specific setting value from an API client GET /api/v2/settings/get{?key,for_client_id}
Get the specified global setting GET /api/v2/settings/get_default{?apiKey}
Get settings from an API client GET /api/v2/settings/get_multi{?keys,for_client_id}
List settings for an API client GET /api/v2/settings/items{?for_client_id}
Get all the setting names for an API client GET /api/v2/settings/keys{?for_client_id}
Configure an API client setting POST /api/v2/settings/set{?key,for_client_id,value}
Configure a global setting POST /api/v2/settings/set_default{?key,value}
Configure multiple global settings POST /api/v2/settings/set_default_multi{?items}
Configure multiple API client settings POST /api/v2/settings/set_multi{?for_client_id,items}
Delete published settings for an API client POST /api/v2/settings/widget/delete{?for_client_id,version,commit}
Get published settings for an API client POST /api/v2/settings/widget/get{?for_client_id,version}
Get published settings for an application POST /api/v2/settings/widget/list{?for_client_id,version}
Publish API client settings POST /api/v2/settings/widget/publish{?for_client_id,include_settings}

Create an API client

Adds a new client to Registration. Once created, your new client will have access to the API, and if applicable, the UI.

POST /api/v2/clients/add{?description,features}

Sample: /api/v2/clients/add?description=This%20client%20is%20for%20US-based%20logins%20and%20registrations.&features=%5B%22login_client%22%5D

Parameter Type Sample Description
Required query parameters
description String This client is for US-based logins and registrations. String description of the client.
Optional query parameters
features String ["login_client"] A JSON array of client features. If not included, the client will be created but will not have any features.

Status 200 application/json

Response body:

{
    "client_id": "12345abcde12345abcde",
    "client_secret": "edcba54321edcba54321",
    "description": "\"Client with direct read access\"",
    "stat": "ok",
    "features": [
        "direct_read_access"
    ]
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode description='Client with direct read access'\
    --data-urlencode features='["direct_read_access"]'\
    https://my-app.janraincapture.com/clients/add

Clear an API client whitelist

Clears the IP whitelist for a target client, resetting it to the default value that allows all IP addresses. Only the owner client may make this API call. The default whitelist is ["0.0.0.0/0"] (all IP addresses are allowed).

POST /api/v2/clients/clear_whitelist{?for_client_id}

Sample: /api/v2/clients/clear_whitelist?for_client_id=67890fghij67890fghij

Parameter Type Sample Description
Optional query parameters
for_client_id String 67890fghij67890fghij The ID for the client whose whitelist will be cleared. If this parameter is not included, the whitelist for the owner client will be cleared.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=67890fghij67890fghij \
    https://my-app.janraincapture.com/clients/clear_whitelist"stat": "ok"

Delete an API client

Deletes a client. Only the owner client may make this API call.

POST /api/v2/clients/delete{?client_id_for_deletion}

Sample: /api/v2/clients/delete?client_id_for_deletion=67890fghij67890fghij

Parameter Type Sample Description
Required query parameters
client_id_for_deletion String 67890fghij67890fghij The ID of the client to be deleted.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode client_id_for_deletion=67890fghij67890fghij \
    https://my-app.janraincapture.com/clients/delete

List API clients

Get a list of the clients in your application, optionally filtered by client feature. Only the owner client can make this API call.

GET /api/v2/clients/list{?has_features}

Sample: /api/v2/clients/list?has_features=%5B%22direct_access%22%2C%20%22access_issuer%22%5D

Parameter Type Sample Description
Optional query parameters
has_features String ["direct_access", "access_issuer"] A JSON array of feature names. Only clients that have at least one of the features in the array will be returned, either owner, access_issuer, direct_read_access, or direct_access.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "results": [
        {
            "client_id": "12345abcde12345abcde",
            "client_secret": "edcba54321edcba54321",
            "description": "application owner",
            "whitelist": [
                "0.0.0.0/0"
            ],
            "features": [
                "access_issuer",
                "direct_access",
                "owner"
            ]
        }
    ]
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode has_features='["direct_access", "access_issuer"]' \
    https://my-app.janraincapture.com/clients/list

Reset an API client secret

Generates a new client secret for a specified client ID. The old client secret will be valid for a specified grace period. If you have a security issue, you can use this endpoint to change a client’s client_secret value instead of generating a new client/secret pair (which would involve changing permissions, access schemas, and hard-coded instances of the credentials). A configurable grace period for the old client_secret value is provided to allow changeover before the new secret breaks existing code.

POST /api/v2/clients/reset_secret{?for_client_id,hours_to_live}

Sample: /api/v2/clients/reset_secret?for_client_id=67890fghij67890fghij&hours_to_live=12

Parameter Type Sample Description
Required query parameters
for_client_id String 67890fghij67890fghij Client ID for the client whose secret is being reset.
hours_to_live String 12 Integer value between 0 and 168, inclusive, that determines the number of hours in which the old client secret remains valid.

Status 200 application/json

Response body:

{
    "new_secret": "abcde12345abcde12345abcde12345",
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=67890fghij67890fghij \
    --data-urlencode hours_to_live=24\
    https://my-app.janraincapture.com/clients/reset_secret

Set an API client description

Change the description of a client. This can also be thought of as the name of the client. This API call can only be made by the owner client.

POST /api/v2/clients/set_description{?description,for_client_id}

Sample: /api/v2/clients/set_description?description=This%20client%20is%20for%20US-based%20logins%20and%20registrations.&for_client_id=67890fghij67890fghij

Parameter Type Sample Description
Required query parameters
description String This client is for US-based logins and registrations. New description for the client.
Optional query parameters
for_client_id String 67890fghij67890fghij Client ID for the client whose description is being changed. If this parameter is not present, the description of the owner client is changed.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=67890fghij67890fghij \
    --data-urlencode description='New client description'\
    https://my-app.janraincapture.com/clients/set_description

Set API client features

Changes the features that a target client has by overwriting the old feature list. This API call may only be made by the client’s owner. The owner client may not remove the owner feature from itself. You can assign more than one owner client.

POST /api/v2/clients/set_features{?features,for_client_id}

Sample: /api/v2/clients/set_features?features=%5B%22owner%22%5D&for_client_id=67890fghij67890fghij

Parameter Type Sample Description
Required query parameters
features String ["owner"] JSON array of features being assigned to the client, any of the following values: owner, access_issuer, direct_read_access, direct_access, or login_client.
Optional query parameters
for_client_id String 67890fghij67890fghij Client ID for the client being modified. If this parameter is not present, feature sets are updated on the owner client.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=67890fghij67890fghij \
    --data-urlencode features='["owner"]'\
    https://my-app.janraincapture.com/clients/set_features

Set an API client whitelist

Change the IP whitelist for a target client, overwriting the previous whitelist. Only the client with the owner feature may make this API call. If the owner client sets the whitelist for itself, the whitelist must allow access from the IP address making the call. All new clients begin with a default whitelist of ["0.0.0.0/0"] (meaning that all IP addresses are allowed).

POST /api/v2/clients/set_whitelist{?whitelist,for_client_id}

Sample: /api/v2/clients/set_whitelist?whitelist=%5B%22192.168.1.61/32%22%5D&for_client_id=67890fghij67890fghij

Parameter Type Sample Description
Required query parameters
whitelist String ["192.168.1.61/32"] The ID of the client whose whitelist is to be modified. If this parameter is not present then the owner client’s whitelist will be modified.
Optional query parameters
for_client_id String 67890fghij67890fghij The ID of the client whose whitelist is to be modified. If this parameter is not present then the owner client’s whitelist will be modified.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=67890fghij67890fghij \
    --data-urlencode whitelist='["123.4.5.6/7890"]'\
    https://my-app.janraincapture.com/clients/set_whitelist

Delete a setting from an API client

Deletes a key from the settings for a particular client. Returns a boolean indicating whether the key existed. This does not modify the application-wide default value for a key.

POST /api/v2/settings/delete{?for_client_id,key}

Sample: /api/v2/settings/delete?for_client_id=fghi7890fghi7890&key=owner

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the client whose key will be deleted. Only the application owner is authorized to send requests using this parameter.
key String owner Key to be deleted from the client settings. You can use the /settings/keys endpoint to return a list of available keys.

Status 200 application/json

Response body:

{
    "result": true,
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890\
    --data-urlencode key=owner \
    https://my-app.janraincapture.com/settings/delete

Remove a key from an application

Deletes a key from the application-wide default settings. Returns a boolean indicating whether the key existed. This does not modify any per-client settings.

POST /api/v2/settings/delete_default{?key}

Sample: /api/v2/settings/delete_default?key=login_attempts

Parameter Type Sample Description
Required query parameters
key String login_attempts Key to be deleted from the application settings. You can use the /settings/keys endpoint to return a list of available keys.

Status 200 application/json

Response body:

{
    "result": false,
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode key=foo \
   https://my-app.janraincapture.com/settings/delete_default

Get a specific setting value from an API client

Returns the value associated with a key for a particular client_id. If the key has no value for that client, then the application-wide default value for that key is returned. If the key has no application default value, then null is returned.

GET /api/v2/settings/get{?key,for_client_id}

Sample: /api/v2/settings/get?key=owner&for_client_id=fghi7890fghi7890

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the client to retrieve the key from. Only the application owner is authorized to send requests using this parameter.
key String owner Key to be retrieved. You can use the /settings/keys endpoint to return a list of available keys.

Status 200 application/json

Response body:

{
    "result": "Jay",
    "stat": "ok"
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode key=owner \
    https://my-app.janraincapture.com/settings/get

Get the specified global setting

Returns the application-wide default value of a key. Returns the value of the key or null if no such key exists.

GET /api/v2/settings/get_default{?apiKey}

Sample: /api/v2/settings/get_default?apiKey=owner

Parameter Type Sample Description
Required query parameters
apiKey String owner Key whose value is to be retrieved. You can use the /settings/keys endpoint to return a list of available keys.

Status 200 application/json

Response body:

{
    "result": "null",
    "stat": "ok"
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode key=owner \
    https://my-app.janraincapture.com/settings/get_default

Get settings from an API client

Key whose value is to be retrieved. You can use the /settings/keys endpoint to return a list of available keys.

GET /api/v2/settings/get_multi{?keys,for_client_id}

Sample: /api/v2/settings/get_multi?keys=%5B%22owner%22%2C%22public%22%2C%22level%22%5D&for_client_id=fghi7890fghi7890

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the client whose keys are being retrieved. Only the application owner is authorized to send requests using this parameter.
keys String ["owner","public","level"] JSON array of the keys to be retrieved.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "result": {
        "public": "true",
        "owner": "Jay",
        "level": "10"
    }
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode keys='["owner","public","level"]' \
    https://my-app.janraincapture.com/settings/get_multi

List settings for an API client

Returns all the settings for a particular client, including those from the application-wide default settings. If a key is defined in both the client and application settings, only the client-specific value is returned. Returns a JSON object of all key-value pairs.

GET /api/v2/settings/items{?for_client_id}

Sample: /api/v2/settings/items?for_client_id=fghi7890fghi7890

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the client whose settings are being retrieved. Note that only the application owner is authorized to send requests using this parameter.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "result": {
        "public": "true",
        "owner": "Jay",
        "level": "10"
    }
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890 \
    https://my-app.janraincapture.com/settings/items

Get all the setting names for an API client

Returns all the keys for a particular client, including those from the application-wide default settings. Returns an array of the keys.

GET /api/v2/settings/keys{?for_client_id}

Sample: /api/v2/settings/keys?for_client_id=fghi7890fghi7890

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the client whose keys are being retrieved. Note that only the application owner is authorized to make requests using this parameter.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "result": [
        "level",
        "owner",
        "public"
    ]
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890 \
    https://my-app.janraincapture.com/settings/keys

Configure an API client setting

Assign a key-value pair for a particular client_id. If the key does not exist, it will be created. If the key already exists, this call overwrites the existing value. Returns a boolean that indicates whether the key already existed. A true value indicates the key has been overwritten. a false value indicates that a new key has been created.

POST /api/v2/settings/set{?key,for_client_id,value}

Sample: /api/v2/settings/set?key=owner&for_client_id=fghi7890fghi7890&value=Robert

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the client whose settings are being modified. Note that only the application owner is authorized to send requests using this parameter.
key String owner Key to add or modify.
value String Robert Value assigned to the key being added or modified.

Status 200 application/json

Response body:

{
    "result": false,
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890\
    --data-urlencode key=owner \
    --data-urlencode value=Robert \
    https://my-app.janraincapture.com/settings/set

Configure a global setting

Set a key in the application-wide default settings. This will create a new key with a default value if the key does not yet exist in the application. If the key does exist, the value will be overwritten. Returns a boolean that indicates whether the key already existed. true indicates that the key has been overwritten, whereas false indicates that a new key has been created.

POST /api/v2/settings/set_default{?key,value}

Sample: /api/v2/settings/set_default?key=permissions&value=Robert

Parameter Type Sample Description
Required query parameters
key String permissions The key being added or modified.
value String Robert Value assigned to the key being added or modified.

Status 200 application/json

Response body:

{
    "result": false,
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode key=permissions \
    --data-urlencode value=default \
    https://my-app.janraincapture.com/settings/set_default

Configure multiple global settings

Assign multiple keys in the application-wide default settings. This will create a new key with a default value if the key does not yet exist in the application. If the key does exist, the value will be overwritten. Returns a boolean value that indicates whether the key already existed. A true value means the key has been overwritten, whereas false means a new key has been created.

POST /api/v2/settings/set_default_multi{?items}

Sample: /api/v2/settings/set_default_multi?items=%7B%22owner%22%3A%22Jay%22%2C%20%22public%22%3A%22true%22%2C%20%22level%22%3A%2210%22%7D

Parameter Type Sample Description
Required query parameters
items String {"owner":"Jay", "public":"true", "level":"10"} JSON object containing the key-value pairs being assigned to the client.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "result": {
        "public": false,
        "owner": false,
        "level": false
    }
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode items='{"owner":"Jay","public":"true","level":"10"}' \
    https://my-app.janraincapture.com/settings/set_default_multi

Configure multiple API client settings

Assign multiple settings for a particular client_id. Returns a JSON object in which each key is mapped to a boolean that indicates whether the key already existed. A true value indicates that a previous key did exist and has been overwritten, whereas false indicates that there was no previous key and a new key has been created. All values for the items parameter must be passed as strings inside quotations. Does not modify application-wide settings.

POST /api/v2/settings/set_multi{?for_client_id,items}

Sample: /api/v2/settings/set_multi?for_client_id=fghi7890fghi7890&items=%7B%22owner%22%3A%22Jay%22%2C%20%22public%22%3A%22true%22%2C%20%22level%22%3A%2210%22%7D

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID for the client being assigned the key-value pairs. Only the application owner is authorized to send request using this parameter.
items String {"owner":"Jay", "public":"true", "level":"10"} JSON object containing the key-value pairs being assigned to the client.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "result": {
        "owner": true,
        "public": false,
        "level": false
    }
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890 \
    --data-urlencode items='{"owner":"Jay","public":"true","level":"10"}' \
    https://my-app.janraincapture.com/settings/set_multi

Delete published settings for an API client

Deletes the published settings for the specified API client and version. If the version parameter is not included, all versions of the settings published for the API client will be deleted. See settings/widget/publish for more information on published settings.

POST /api/v2/settings/widget/delete{?for_client_id,version,commit}

Sample: /api/v2/settings/widget/delete?for_client_id=fghi7890fghi7890&version=123abc45-de67-fgh8-9ijk–0lmn123op45q&commit=true

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the API client whose settings are being deleted.
Optional query parameters
commit Boolean true Set to true in order to delete the settings. The default value is false.
version String 123abc45-de67-fgh8-9ijk-0lmn123op45q Version number of the settings to be deleted.

Status 200 application/json

Response body:

{
    "results": "The settings files were deleted",
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890\
    --data-urlencode version=123abc45-de67-fgh8-9ijk-0lmn123op45q \
    --data-urlencode commit=true\
    https://my-app.janraincapture.com/settings/widget/delete

Get published settings for an API client

Returns the published settings for the specified API client and version. If the version parameter is not included, the most recent version of the published settings will be returned. See settings/widget/publish for more information on published settings.

POST /api/v2/settings/widget/get{?for_client_id,version}

Sample: /api/v2/settings/widget/get?for_client_id=fghi7890fghi7890&version=123abc45-de67-fgh8-9ijk–0lmn123op45q

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the API client whose settings are being returned.
Optional query parameters
version String 123abc45-de67-fgh8-9ijk-0lmn123op45q Version number of the settings to be returned.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "results": {
        "janrain_settings_version": "123abc45-de67-fgh8-9ijk-0lmn123op45q",
        "minimum_age": "13"
    }
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890\
    --data-urlencode version=123abc45-de67-fgh8-9ijk-0lmn123op45q \
    https://my-app.janraincapture.com/settings/widget/get

Get published settings for an application

Returns a list of published settings files for the application. At least three files will be returned, one for each version as well as a .json and .js file where the most recently published version is hosted for consumption by the Registration UI. If no parameters are included, all published settings files associated with the application will be listed. All parameters are optional, but if a version is specified the for_client_id parameter must also be included. See settings/widget/publish for more information on published settings.

POST /api/v2/settings/widget/list{?for_client_id,version}

Sample: /api/v2/settings/widget/list?for_client_id=fghi7890fghi7890&version=123abc45-de67-fgh8-9ijk–0lmn123op45q

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the API client whose settings are being returned.
Optional query parameters
version String 123abc45-de67-fgh8-9ijk-0lmn123op45q Version number of the settings to be returned.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "results": [
        "widget_data/settings/789mdu24alp501skrbxz36dw08/12345abcde12345abcde12345abcde12.js",
        "widget_data/settings/789mdu24alp501skrbxz36dw08/12345abcde12345abcde12345abcde12.json",
        "widget_data/settings/789mdu24alp501skrbxz36dw08/12345abcde12345abcde12345abcde12/123abc45-de67-fgh8-9ijk-0lmn123op45q.json",
        "widget_data/settings/789mdu24alp501skrbxz36dw08/12345abcde12345abcde12345abcde12/67890def-6789-defg-6789-67890defgh67.json"
    ]
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890\
    https://my-app.janraincapture.com/settings/widget/list

Publish API client settings

Publish API client settings to a JSON file available for client-side use with the Registration UI. This allows settings to be loaded prior to any server-side calls. Published client settings are typically used to support a configurable minimum age requirement for registration or tracking user acceptance of different terms of service and privacy policies on a per-site basis. The settings to be published for an API client are configured in an additional setting called jump_publish_settings. In order for the Registration UI to load the JavaScript file where these settings are published, the hasSettings JavaScript setting must be set to true.

POST /api/v2/settings/widget/publish{?for_client_id,include_settings}

Sample: /api/v2/settings/widget/publish?for_client_id=fghi7890fghi7890&include_settings=true

Parameter Type Sample Description
Required query parameters
for_client_id String fghi7890fghi7890 Client ID of the API client whose settings are being published.
Optional query parameters
include_settings Boolean true If set to true, published settings are returned as part of the response.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "results": {
        "janrain_settings_version": "123abc45-de67-fgh8-9ijk-0lmn123op45q",
        "minimum_age": "13"
    }
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode for_client_id=fghi7890fghi7890\
    --data-urlencode include_settings=true\
    https://my-app.janraincapture.com/settings/widget/publish

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

Client

Properties and property values for an API client.

Download schema: list.json

Sample GET response:

{
    "stat": "ok",
    "results": [
        {
            "client_id": "12345abcde12345abcde",
            "client_secret": "edcba54321edcba54321",
            "description": "application owner",
            "whitelist": [
                "0.0.0.0/0"
            ],
            "features": [
                "access_issuer",
                "direct_access",
                "owner"
            ]
        }
    ]
}

Client members

Member Type Description
Client: Properties and property values for an API client.
client_id String Unique identifier of the API client.
client_secret String Client secret associated with the API client. When making API calls, the client ID functions as the username and the client secret functions as the password.
description String Brief description of the API client, its properties, and its intended use.
features Array Specifies the features assigned to the API client. Features determine the level of administrative access that API clients have to user records and application management functionality. For example, an owner client has access to all user records, while a login_client client can only access records for the currently authenticated user.
whitelist Array JSON array of CIDR (Classless Inter-Domain Routing) addresses that can be used to access the API client. The default value of 0.0.0.0/0 indicates that the client can be accessed from any IP address.

Secret

Generates a new client secret for the specified API client.

Download schema: reset-secret.json

Sample POST response:

{
    "new_secret": "abcde12345abcde12345abcde12345",
    "stat": "ok"
}

Secret members

Member Type Description
Secret: Generates a new client secret for the specified API client.
new_secret String New client secret assigned to the API client.
stat String Indicates the status of the current operation.

Settings

Returns all the settings for a particular client, including those from the application-wide default settings. If a key is defined in both the client and application settings, only the client-specific value is returned.

Download schema: settings-items.json

Sample GET response:

{
    "stat": "ok",
    "result": {
        "owner": "Jay",
        "public": "true",
        "level": "10"
    }
}

Settings members

Member Type Description
Settings: Returns all the settings for a particular client, including those from the application-wide default settings. If a key is defined in both the client and application settings, only the client-specific value is returned.
result Object Settings configured for the specified API client.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.

Errors

This section provides details on the error responses generated by the Legacy Clients and Settings API.

Error responses

Legacy Clients and Settings API errors are returned as JSON objects similar to the following:

{
    "request_id": "t5qmufuvtbhytg7d",
    "code": 205,
    "error_description": "no authentication provided, for example client_id and client_secret",
    "error": "invalid_auth_method",
    "stat": "error"
}

The stat property indicates that the API call failed. If your API call succeeds, you’ll get a similar response. However, a success response will not have an err section and the stat will be set to ok:

{
    "result": [
        "rpx_app_id",
        "rpx_key",
        "rpx_realm",
        "rpx_server"
    ],
    "stat": "ok"
}

Legacy Clients and Settings API error responses are summarized in the following table:

Code Description
100 Missing required argument.
200 Invalid client ID or client secret.
205 No authentication provided.

The Legacy Clients and Settings API always generates a 200 HTTP response code, even if the API call fails. Because of that, use the error codes summarized above and the stat property to determine the success or failure of an API call.


Last modified: 6/27/2019