Configurations

Before you can start using the Icertis API Developer Experience, you must configure some settings.

Configurations

Before you can start using the Icertis API Developer Experience, you must configure some settings.

Creating the ICM Administrator User

To access Icertis API Developer Experience, the users must be assigned the APIM Dev Portal User role on the ICI platform. We recommend that you create a new ICM Administrator user to grant user the access to the Icertis API Developer Experience.

To create the ICM Administrator user:

  1. Log on to your ICI instance as a user with administrative privileges.

  2. Navigate to Admin > Users > Create a user. Ensure it is an internal user.

  3. Assign the APIM Dev Portal User role to the new user.

Trying our APIs

Add the ici-product-key parameter to try out the APIs. You must request the ICI platform system administrator to provide the value for the ici-product-key parameter.

  1. On the APIs tab, click Icertis Business APIs.

  2. Click the API you want to try.

  3. On the top right corner, click Try it.

  4. In Headers section, click Add header.

  5. In the name field, enter ici-product-key and enter the value.

  6. Click Send.

Gateway URLs

The ICI Developer Experience Gateway URLs have specific format that depends on the region that your instance belongs to.

  • api-<shortform_region_name><region_number>.icertis.com

  • api-<shortform_region_name><region_number>1.icertis.com

  • api-<shortform_region_name><region_number><N-1>.icertis.com

  • api-<shortform_region_name><region_number>-{nonprod}.icertis.com

  • api-<shortform_region_name><region_number>1-{nonprod}.icertis.com

  • api-<shortform_region_name><region_number><N-1>-{nonprod}.icertis.com

To confirm your instance URL, navigate to the APIs tab and check any of the APIs.

Authentication Methods

Icertis API Developer Experience does not have its own native authentication mechanism and do not manage any user credentials. ICI integrates with the customer’s Identity Provider to deliver a seamless SSO experience.

The Icertis API Developer Experience supports the following authentication methods:

  • OAuth 2.0: This is the recommended method for authentication.

  • ICM AuthToken: This authentication method is used only for the testing purpose.

  • Client Certificate: Contact ICI support to use this method for authentication.

OAuth 2.0

This is the recommended method for authentication.

  1. Register the client IDP on the preferred application, such as Azure, Okta, Ping or any other authentication application.

  2. Generate the Client ID and Client Secret on the application.

  3. Fetch the following details from the client and add it to the ICI tenant.json file.

    • Discovery Endpoint also known as .well-known configuration endpoint or OpenID Connect metadata document URL

    • Claim Type to be validated

    • Valid Audience details

    • Valid Issuer details

You can use the OAuth 2.0 method for authentication.

ICM AuthToken

ICMAuthToken is used for testing purpose only.

  • This token is generated against an ICI user and after the specified time the token expires. You can configure the expiration time.

  • Use the following URL to get an ICMAuthToken for testing:
    https://{{customerinstance}}.Icertis.com/userinformation/GetUserApiToken

Ensure that you append the URL with your instance.