Configuration API

Overview

This document describes the API operations for a configuration.

Version information

Version : 1.0.0

URI scheme

Schemes : HTTPS, HTTP

Paths

Obtaining configuration from CIM

GET /api/config

Parameters

Type Name Description Schema
Query fields
optional		 Fields that should be included in the response message. All fields are displayed if the param is not present. < Fields > array

Responses

HTTP Code Description Schema
200 Configuration Configuration
400 Bad request No Content
405 Unsupported method No Content
500 Api disabled No Content

Consumes

  • application/json

Produces

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/config

Example HTTP response

Response 200
{
  "password_policy" : {
    "min_length" : 0,
    "max_length" : 0,
    "lower_case_char_required" : false,
    "upper_case_char_required" : false,
    "special_char_required" : false,
    "breached_password_blocked" : false
  },
  "messages" : {
    "default" : {
      "personal.general.next" : "Next",
      "personal.general.collapse" : "Collapse"
    },
    "nl" : {
      "personal.general.next" : "Volgende",
      "personal.general.collapse" : "Inklappen"
    }
  },
  "profile" : {
    "required_attributes_validation_rules" : [ {
      "any_of" : [ "BIRTH_DATE", "PHONE" ]
    } ]
  }
}

Reloading configuration from extension

POST /api/config/extension/reload

Description

The endpoint allows reloading extension messages and static resources in IdP runtime

Responses

HTTP Code Description Schema
200 Extension configuration reloaded No Content
405 Unsupported method No Content
500 Api disabled No Content

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/config/extension/reload

Resolve information about all configured Identity Providers

GET /api/config/identity-providers

Responses

HTTP Code Description Schema
200 Configured identity providers IdentityProviderConfigResultSet
400 Bad request No Content
405 Unsupported method No Content
500 Api disabled No Content

Produces

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/config/identity-providers

Example HTTP response

Response 200
{
  "result" : [ {
    "id" : "12345",
    "name" : "Facebook",
    "type" : "facebook",
    "saml_properties" : {
      "authn_context" : "urn:com:onegini:saml:facebook"
    }
  } ]
}

Fetch attributes configuration

GET /api/v2/attributes

Responses

HTTP Code Description Schema
200 Attributes configuration fetched successfully\ AttributesConfiguration
401 Unauthorized No Content
409 API disabled No Content

Example HTTP request

Request path
/api/v2/attributes

Example HTTP response

Response 200
{
  "person_creation_mandatory_fields" : {
    "first_name_required" : true,
    "last_name_required" : true,
    "mobile_number_required" : true
  },
  "sign_up_form_fields" : {
    "mobile_number_enabled" : true,
    "mobile_number_confirmation_enabled" : true,
    "email_confirmation_enabled" : true
  },
  "verification" : {
    "email_enabled" : true,
    "email_required" : true,
    "mobile_number_enabled" : true
  },
  "name_visible_on_dashboard" : true
}

Update attributes configuration

PUT /api/v2/attributes

Responses

HTTP Code Description Schema
204 Attributes Configuration updated No Content
401 Unauthorized No Content
409 API disabled No Content

Example HTTP request

Request path
/api/v2/attributes

Update attributes configuration partially

PATCH /api/v2/attributes

Responses

HTTP Code Description Schema
201 Attributes Configuration updated No Content
401 Unauthorized No Content
409 API disabled No Content

Example HTTP request

Request path
/api/v2/attributes

Obtain configuration from CIM

GET /api/v2/config

Responses

HTTP Code Description Schema
200 Configuration fetched successfully CIMConfiguration
409 API disabled No Content

Produces

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/v2/config

Example HTTP response

Response 200
{
  "custom_messages" : {
    "default" : {
      "personal.general.next" : "Next",
      "personal.general.collapse" : "Collapse"
    },
    "locales" : {
      "locales" : {
        "nl" : {
          "personal.general.next" : "Volgende",
          "personal.general.collapse" : "Inklappen"
        }
      }
    }
  },
  "features" : {
    "login_enabled" : true,
    "sign_up_enabled" : true,
    "automated_external_identity_coupling_enabled" : true,
    "bind_multiple_external_accounts_with_one_cim_account" : true,
    "accepting_invitation_enabled" : true,
    "post_login_extra_registration_after_second_login" : true,
    "action_token" : {
      "login" : {
        "enabled" : true,
        "ttl" : 0,
        "authentication_level" : 0,
        "ui_generation_enabled" : true
      },
      "app_to_web" : {
        "enabled" : true,
        "ttl" : 0,
        "authentication_level" : 0
      },
      "coupling" : {
        "enabled" : true,
        "ttl" : 0
      },
      "whitelisted_urls" : [ {
        "id" : "string",
        "url" : "string"
      } ]
    },
    "person_activation" : {
      "enabled" : true,
      "expiration_time" : 0,
      "type" : "string",
      "externally_delivered_code" : {
        "unavailability_time" : 0,
        "resend_code_minimum_period" : 0
      }
    },
    "password_reset_enabled" : true,
    "username_reminder_via_sms_enabled" : true,
    "mobile_number_validation_backend_services_enabled" : true,
    "custom_email_validation" : {
      "enabled" : true,
      "before_at_regex" : "string",
      "after_at_regex" : "string"
    },
    "migration_enabled" : true,
    "unauthenticated_migration_enabled" : true,
    "person_identifier_in_external_profile_required_for_migration" : true,
    "invitation_verification_required" : {
      "via_birthdate_enabled" : true,
      "via_sms_enabled" : true,
      "via_externally_delivered_code_enabled" : true
    },
    "allow_sign_up_without_invitation_validation" : true,
    "pin_enabled" : true,
    "sms_enabled" : true,
    "google_authenticator_step_up_authentication_enabled" : true,
    "mobile_authentication_enabled" : true,
    "step_up_authentication_method_externally_delivered_code_enabled" : true,
    "id_check_enabled" : true,
    "cookie_based_saml_authentication" : true,
    "person_api_enabled" : true,
    "credentials_api_enabled" : true,
    "configuration_api_enabled" : true,
    "events_api_enabled" : true,
    "statistics_api_enabled" : true,
    "session_api_enabled" : true,
    "storage_api_enabled" : true,
    "experimental_features_enabled" : true
  }
}

Update set of CIM's configuration units

PUT /api/v2/config

Responses

HTTP Code Description Schema
204 Configuration updated successfully Configuration
400 Bad request No Content
409 API disabled No Content

Consumes

  • application/json

Example HTTP request

Request path
/api/v2/config

Example HTTP response

Response 204
{
  "password_policy" : {
    "min_length" : 0,
    "max_length" : 0,
    "lower_case_char_required" : false,
    "upper_case_char_required" : false,
    "special_char_required" : false,
    "breached_password_blocked" : false
  },
  "messages" : {
    "default" : {
      "personal.general.next" : "Next",
      "personal.general.collapse" : "Collapse"
    },
    "nl" : {
      "personal.general.next" : "Volgende",
      "personal.general.collapse" : "Inklappen"
    }
  },
  "profile" : {
    "required_attributes_validation_rules" : [ {
      "any_of" : [ "BIRTH_DATE", "PHONE" ]
    } ]
  }
}

Get custom messages for all languages and configured variants

GET /api/v2/config/custom-messages

Responses

HTTP Code Description Schema
200 Custom messages fetched successfully No Content
401 Unauthorized No Content
409 API disabled No Content
500 Internal server error No Content

Example HTTP request

Request path
/api/v2/config/custom-messages

Update custom messages configuration

PUT /api/v2/config/custom-messages

Responses

HTTP Code Description Schema
204 Custom messages updated successfully No Content
400 Bad Request No Content
401 Unauthorized No Content
409 API disabled No Content

Example HTTP request

Request path
/api/v2/config/custom-messages

Create or update multiple custom messages for a given locale

PUT /api/v2/config/custom-messages/{locale_variant}/batch

Parameters

Type Name Schema
Path locale_variant
required		 string

Responses

HTTP Code Description Schema
204 Custom messages for given locale created or updated No Content
401 Unauthorized No Content
409 API disabled No Content
500 Internal server error No Content

Example HTTP request

Request path
/api/v2/config/custom-messages/string/batch

Remove custom message for a given locale

DELETE /api/v2/config/custom-messages/{locale_variant}/{message_key}

Parameters

Type Name Description Schema
Path locale_variant
required		 locale with variant code string
Path message_key
required		 message's key to remove string

Responses

HTTP Code Description Schema
204 Custom message with given key deleted successfully No Content
401 Unauthorized No Content
409 API disabled No Content
500 Internal server error No Content

Example HTTP request

Request path
/api/v2/config/custom-messages/string/string

Fetch features configuration

GET /api/v2/config/features

Responses

HTTP Code Description Schema
200 Features config fetched successfully No Content
409 API disabled No Content
500 Internal server error No Content
content No Content

Example HTTP request

Request path
/api/v2/config/features

Update features configuration

PUT /api/v2/config/features

Responses

HTTP Code Description Schema
204 Features config updated successfully No Content
409 API disabled No Content

Example HTTP request

Request path
/api/v2/config/features

Update part of features configuration

PATCH /api/v2/config/features

Responses

HTTP Code Description Schema
204 Features config updated successfully No Content
409 API disabled No Content

Example HTTP request

Request path
/api/v2/config/features

Add url to action token whitelisted urls

POST /api/v2/config/features/action-token/whitelisted-urls

Responses

HTTP Code Description Schema
201 Whitelisted url added successfully No Content
409 API disabled No Content
500 Internal server error No Content

Example HTTP request

Request path
/api/v2/config/features/action-token/whitelisted-urls

Fetch whitelisted urls for action token

GET /api/v2/config/features/action-token/whitelisted-urls

Responses

HTTP Code Description Schema
200 Whitelisted urls fetched successfully No Content
409 API disabled No Content
500 Internal server error No Content
content No Content

Example HTTP request

Request path
/api/v2/config/features/action-token/whitelisted-urls

Delete whitelisted url by id

DELETE /api/v2/config/features/action-token/whitelisted-urls/{url-id}

Parameters

Type Name Schema
Path url-id
required		 string

Responses

HTTP Code Description Schema
204 whitelisted url deleted No Content
401 Unauthorized No Content
409 API disabled No Content
500 Internal server error No Content

Example HTTP request

Request path
/api/v2/config/features/action-token/whitelisted-urls/string

Definitions

ActionTokenApp2WebLogin

Name Description Schema
authentication_level
optional		 Example : 0 integer
enabled
optional		 Example : true boolean
ttl
optional		 Example : 0 integer

ActionTokenConfiguration

Name Description Schema
app_to_web
optional		 Example : "[actiontokenapp2weblogin](#actiontokenapp2weblogin)" ActionTokenApp2WebLogin
coupling
optional		 Example : "[actiontokencoupling](#actiontokencoupling)" ActionTokenCoupling
login
optional		 Example : "[actiontokenlogin](#actiontokenlogin)" ActionTokenLogin
whitelisted_urls
optional		 redirect url whitelist
Example : [ "[whitelistedurl](#whitelistedurl)" ]		 < WhitelistedUrl > array

ActionTokenCoupling

Name Description Schema
enabled
optional		 Example : true boolean
ttl
optional		 Example : 0 integer

ActionTokenLogin

Name Description Schema
authentication_level
optional		 Example : 0 integer
enabled
optional		 Example : true boolean
ttl
optional		 Example : 0 integer
ui_generation_enabled
optional		 Example : true boolean

AttributeType

Type : enum (NAME, PHONE, BIRTH_DATE, EMAIL)

AttributesConfiguration

Name Description Schema
name_visible_on_dashboard
optional		 Example : true boolean
person_creation_mandatory_fields
optional		 Example : "[personcreationmandatoryattributes](#personcreationmandatoryattributes)" PersonCreationMandatoryAttributes
sign_up_form_fields
optional		 Example : "[signupformfields](#signupformfields)" SignUpFormFields
verification
optional		 Example : "[attributesverification](#attributesverification)" AttributesVerification

AttributesVerification

Name Description Schema
email_enabled
optional		 Example : true boolean
email_required
optional		 Example : true boolean
mobile_number_enabled
optional		 Example : true boolean

CIMConfiguration

Name Description Schema
custom_messages
optional		 Example : "[custommessages](#custommessages)" CustomMessages
features
optional		 Example : "[featuresconfiguration](#featuresconfiguration)" FeaturesConfiguration

Configuration

Name Description Schema
messages
required		 Example : "[messages](#messages)" Messages
password_policy
required		 Example : "[passwordpolicy](#passwordpolicy)" PasswordPolicy
profile
optional		 Example : "[profile](#profile)" Profile

CustomEmailValidation

Name Description Schema
after_at_regex
optional		 regex for validating domain part of email
Example : "string"		 string
before_at_regex
optional		 regex for validating local part of email
Example : "string"		 string
enabled
optional		 Example : true boolean

CustomMessages

Name Description Schema
default
optional		 key value map of default custom messages
Example : {<br> "personal.general.next" : "Next",<br> "personal.general.collapse" : "Collapse"<br>}		 < string, string > map
locales
optional		 Example : {<br> "locales" : {<br> "nl" : {<br> "personal.general.next" : "Volgende",<br> "personal.general.collapse" : "Inklappen"<br> }<br> }<br>} < string, < string, string > map > map

ExternallyDeliveredCode

Name Description Schema
resend_code_minimum_period
optional		 Example : 0 integer
unavailability_time
optional		 Example : 0 integer

FeaturesConfiguration

Name Description Schema
accepting_invitation_enabled
optional		 Example : true boolean
action_token
optional		 Example : "[actiontokenconfiguration](#actiontokenconfiguration)" ActionTokenConfiguration
allow_sign_up_without_invitation_validation
optional		 Example : true boolean
automated_external_identity_coupling_enabled
optional		 Example : true boolean
bind_multiple_external_accounts_with_one_cim_account
optional		 Example : true boolean
configuration_api_enabled
optional		 Example : true boolean
cookie_based_saml_authentication
optional		 Example : true boolean
credentials_api_enabled
optional		 Example : true boolean
custom_email_validation
optional		 Example : "[customemailvalidation](#customemailvalidation)" CustomEmailValidation
events_api_enabled
optional		 Example : true boolean
experimental_features_enabled
optional		 Example : true boolean
google_authenticator_step_up_authentication_enabled
optional		 Example : true boolean
id_check_enabled
optional		 Example : true boolean
invitation_verification_required
optional		 Example : "[invitationverification](#invitationverification)" InvitationVerification
login_enabled
optional		 Example : true boolean
migration_enabled
optional		 Example : true boolean
mobile_authentication_enabled
optional		 Example : true boolean
mobile_number_validation_backend_services_enabled
optional		 Example : true boolean
password_reset_enabled
optional		 Example : true boolean
person_activation
optional		 Example : "[personactivationconfiguration](#personactivationconfiguration)" PersonActivationConfiguration
person_api_enabled
optional		 Example : true boolean
person_identifier_in_external_profile_required_for_migration
optional		 Example : true boolean
pin_enabled
optional		 Example : true boolean
post_login_extra_registration_after_second_login
optional		 Example : true boolean
session_api_enabled
optional		 Example : true boolean
sign_up_enabled
optional		 Example : true boolean
sms_enabled
optional		 Example : true boolean
statistics_api_enabled
optional		 Example : true boolean
step_up_authentication_method_externally_delivered_code_enabled
optional		 Example : true boolean
storage_api_enabled
optional		 Example : true boolean
unauthenticated_migration_enabled
optional		 Example : true boolean
username_reminder_via_sms_enabled
optional		 Example : true boolean

Fields

Type : enum (profile, messages, password_policy)

IdentityProviderConfig

Name Description Schema
id
optional		 Example : "12345" string
name
optional		 Example : "Facebook" string
saml_properties
optional		 Example : "[samlproperties](#samlproperties)" SamlProperties
type
optional		 Example : "facebook" string

IdentityProviderConfigResultSet

Name Description Schema
result
optional		 Example : [ "[identityproviderconfig](#identityproviderconfig)" ] < IdentityProviderConfig > array

InvitationVerification

Name Description Schema
via_birthdate_enabled
optional		 Example : true boolean
via_externally_delivered_code_enabled
optional		 Example : true boolean
via_sms_enabled
optional		 Example : true boolean

LocaleCustomMessages

key value map of custom messages

Name Description Schema
additionalProperties
optional		 Example : "string" string

Messages

Key value map where key is the language nad value contains list of translations.

Type : < string, < string, Translations > map > map

PasswordPolicy

Name Description Schema
breached_password_blocked
required		 Indicates that the password is disallowed when it has been discovered in a public data breach.
Note: this option enables sending an anonymized transformation of the user's password to the Have I Been Pwned API, which is a resource of passwords found in public data breaches. This information is sent in such a way that it cannot be linked to the original user or their password by anyone (more on how this works).
Example : false		 boolean
lower_case_char_required
required		 Indicates at least one lower case character is required.
Example : false		 boolean
max_length
required		 Indicates the maximum length of a password.
Example : 0		 integer (int32)
min_length
required		 Indicates the minimum length of a password.
Example : 0		 integer (int32)
special_char_required
required		 Indicates that at least one special character is required.
Example : false		 boolean
upper_case_char_required
required		 Indicates at least one upper case character is required.
Example : false		 boolean

PersonActivationConfiguration

Name Description Schema
enabled
optional		 Example : true boolean
expiration_time
optional		 Example : 0 integer
externally_delivered_code
optional		 Example : "[externallydeliveredcode](#externallydeliveredcode)" ExternallyDeliveredCode
type
optional		 Example : "string" enum (EMAIL, EXTERNALLY_DELIVERED_CODE)

PersonCreationMandatoryAttributes

Name Description Schema
first_name_required
optional		 Example : true boolean
last_name_required
optional		 Example : true boolean
mobile_number_required
optional		 Example : true boolean

Profile

Contains profile configuration

Name Description Schema
required_attributes_validation_rules
optional		 Example : [ "[requiredattributesvalidationrule](#requiredattributesvalidationrule)" ] < RequiredAttributesValidationRule > array

RequiredAttributesValidationRule

Contains list of required profile attributes. At least one of attributes is required

Name Description Schema
any_of
optional		 Example : [ "BIRTH_DATE", "PHONE" ] < AttributeType > array

SamlProperties

Name Description Schema
authn_context
optional		 Example : "urn:com:onegini:saml:facebook" string

SignUpFormFields

Name Description Schema
email_confirmation_enabled
optional		 Example : true boolean
mobile_number_confirmation_enabled
optional		 Example : true boolean
mobile_number_enabled
optional		 Example : true boolean

Translations

Key value map where key is the message identifier and value contains translation.

Type : < string, string > map

WhitelistedUrl

Name Description Schema
id
optional
read-only		 id of a given url
Example : "string"		 string (uuid)
url
optional		 url value
Example : "string"		 string

WhitelistedUrls

Name Description Schema
whitelisted_urls
optional		 redirect url whitelist
Example : [ "[whitelistedurl](#whitelistedurl)" ]		 < WhitelistedUrl > array

Security

basic_auth

Type : basic