Configure API

25 Mar 2025
10 Minutes to read

Configure API

Updated on 25 Mar 2025
10 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback

Configure API

Effective API configuration is crucial for smooth communication between different software systems, ensuring that data is exchanged accurately and securely. To configure API, perform the following steps.

Important Notes

The API Configuration that is set up in the current screen is widely utilized across various modules within our system. This includes, but is not limited to, the following:

Azure User Import: The integration with Microsoft Azure to import user details relies on the API settings for secure and accurate data retrieval.
OKTA AD Import: Similarly, the API Configuration is key for connecting with Okta's Active Directory to import user information in a consistent and reliable manner.
BRD: Business Rule Designer (BRD) module leverages the API Configuration for various operations.
Scheduler: The Scheduler module uses the API settings for tasks that involve interfacing with external services to trigger events or actions at specified times.
SMTP: Simple Mail Transfer Protocol (SMTP) settings for sending out emails are dependent on the API Configuration to ensure emails are delivered securely and efficiently.
SMS: For sending text messages, the SMS module relies heavily on the API Configuration to connect with telecommunication service providers.
Mailbox: The Mailbox module also uses the API Configuration to interact with email services, managing incoming and outgoing communications effectively.

It is crucial to recognize that any changes to the API Configuration could potentially impact all the above modules and their related functionalities. Therefore, extreme caution should be exercised when making modifications to the API settings to avoid any disruptions in service and ensure continuous and seamless operation across the system.

To configure API, perform the following steps:

Navigate to Design Studio > Select Module > Designers > API Configuration.
Select the Domain and Sub Domain from the drop-down menu. The list of configured API is displayed based on Tenants. To learn more on how to manage the list page, navigate to Manage API Configuration.
Click New to add API Configuration.
Figure: API Configuration List
Enter the required details on the API Configuration Page and click Save to add the configuration to the app system.
Figure: New API Configuration

API Configuration Details

The General Properties for an API is configured in this section, such as API Name, Group Name and API Type.

Figure: API Configuration Details.

Enter an unique API Name.
Select API GroupName from the dropdown list. All the similar APIs are grouped under the single API Group for easier identification.
Following are list of API Group Names in the dropdown list.

For more information about the API Groups, refer to the following:

Microsoft Teams

Internal API

Microsoft Entra ID

Okta Active Directory

Others

When configuring APIs that use Microsoft Teams as the API group, you're typically working with Microsoft Graph API, which provides a unified endpoint to access Microsoft 365 services, including Teams.

Below are a few examples of API configurations that are under the Microsoft Teams API Group:

Send a Message to a Channel:

Method: POST
URL: https://graph.microsoft.com/{version}/{resource}?[query_parameters]
Description: Sends a message to a specific channel in a team.

Get Messages from a Channel:

Method: GET
URL: https://graph.microsoft.com/{version}/{resource}?[query_parameters]
Description: Retrieves messages from a specific channel in a team.

Note
These configurations use Microsoft Graph API endpoints designed to interact with Microsoft Teams.

Internal APIs are used within a specific organization or set of systems, rather than being publicly available for external developers. These APIs often facilitate communication between different internal services, applications, or components.

Internal APIs are typically secured within the company’s network and are often safeguarded by firewalls, VPNs, or other security protocols to prevent unauthorized access. They are designed in a way to match the specific needs of the organization, reflecting its processes and operational requirements.

Consider the following example of API configurations that uses Internal API.

To Deallocate an SW asset from the Inventory the Following API is used.

Application: Asset Management
API Name: Inventory SW - Deallocate
API Group: Internal API
API Type: Internal
Method: POST
URL: https://<url-details>api/FormUpdateQuery
Authentication: API Key
Body: Request Type JSON
{JSON Body}

Microsoft Entra ID, formerly known as Azure Active Directory (Azure AD), is Microsoft's cloud-based identity and access management service. This forms the identity backbone for Microsoft services, can be managed and interacted with using the Microsoft Graph API. The Microsoft Graph API provides a comprehensive endpoint (https://graph.microsoft.com) to access Microsoft 365 services and data, enabling developers to programmatically manage users, groups, applications, and more within Microsoft Entra ID. Which includes, user management, authentication, role-based access control (RBAC), and Single Sign-On (SSO).

Below is an example of how you can use the Microsoft Graph API for various tasks related to Microsoft Entra ID.

List Users

Method: GET
URL: https://graph.microsoft.com/v1.0/users

Okta is a leading identity and access management service that integrates with existing solutions like Active Directory (AD) to provide secure and streamlined identity management for organizations. While Okta itself is not an Active Directory service, it can connect to AD to enhance Directory Integration.

API Endpoints: Okta provides REST APIs for integrating and managing directory information.

Add AD Integration: Add an AD as an identity provider in Okta
Method: POST
URL: https://<url-details>/api/v1/idps
Sync Directory User: Synchronize a user from a directory.
Method: POST
URL: https://<url-details>/api/v1/users/{userId}/lifecycle/sync

By integrating Okta with Active Directory using its robust set of APIs, organizations can enhance their identity and access management capabilities, automate user provisioning, and provide secure access to applications, both on-premises and in the cloud.

Selecting this will enable you to configure API for Third Party Authentication Services

Select the purpose for which the API is Configured For from the dropdown.

Configure For	Description
SMTP Gateway	Configuring an API for an SMTP Gateway involves setting up an interface that allows applications to programmatically interact with an SMTP server to send emails. This setup is common for applications that require automated email notifications, alerts, or communication features.
SMS Gateway	Allowing sending SMS messages via an API
Inbound	Processing incoming API requests from external clients.
Outbound	Sending data from an internal system to an external CRM or database.
MS Teams	Integration of an API with Microsoft Teams to send and receive messages, manage channels, and automate workflows.
Slack	Slack API configuration allows sending messages, managing users, and integrating workflows.
Mailbox	API configuration for a Mailbox means integrating with an email system (example: Outlook, Gmail) to send and receive emails.
Webhook	Webhooks allow applications to push data when an event occurs.

Select the platform components and the API availability for use in the application.
For more information on Field Description, refer the following table:

Field	Description
Domain	Domain is the highest level of hierarchy. It is the main identity of a parent company with different subsidiaries.
Sub Domain	A Sub Domain is the second level of hierarchy. It is chosen as a drop-down menu based on Domain selection.
Department	Choose the Tenant from the drop-down menu. It is a unit in an organization that provides support to different functions. Example: IT, Facilities etc.
Active	Active Switch is enabled by default, while configuring a new API. Having this enabled will allow the application to use the API.
Icon	Choose an icon to be uploaded for the specified API. The maximum upload file size is 1MB Image dimensions should not exceed 50px X 50px Supported imag formats are .gif, .jpeg, .jpg, .png, .bmp. The images will display as shown below while using the Call API functionality.

API Details

The API Details section lists the following field that needs to be defined. For more information, refer to the table below.

Field	Description
API Name	Specify a unique name for the API.
API Timeout (In seconds)	Enter a numeric value for specifying the API timeout (In seconds).
API Type	Select the API from the drop-down menu. Following are options in the dropdown list. External - An External API is accessible to users, developers, or third-party organizations outside of the company. Internal - An Internal API is designed for use within an organization. It is not exposed to external users or developers.
Response Type	Specify the Response Type as Array or Object. Array - An Array in an API response contains a list of multiple objects, enclosed in [] (square brackets). Each item in the array follows the same structure. Object - An Object in an API response refers to a single structured data entity enclosed in {} (curly braces). It consists of key-value pairs where each key represents a specific field.
Method	Specify the method available to be configured for the API from the drop-down menu. Example: Get, Post, Put etc. Get - Retrieve data from the server. Post - Send new data to the server. Put - Update existing data on the server.
URL	Specify a validated URL.
Add to List	Select the button to add the configured parameters to the list.

Authentication

Params

Header

Body

Response

Authentication
Authentication Type	Choose the predefined values from the drop-down list. Example: No Authentication, API Key, Bearer Token, Basic, OAuth 2.0.
URL	Enter the URL details for the API.
Authentication Types	No Authentication
API Key	API Key - In API configuration, API Key & Value authentication is a method of securing access to an API by requiring clients to provide a unique key-value pair. The API provider usually provides this key and acts as a form of credential to verify and authorize requests.
Bearer Token	Bearer Token - A Bearer Token is a security token used in authentication and authorization to access protected resources in an API. It follows the OAuth 2.0 authentication framework and is called a "bearer" token because the user (or system) presenting the token is assumed to be authenticated without needing further proof.
Basic	Basic - Basic Authentication is a simple and widely used method for securing APIs. It involves sending a username and password in the request header, which the server validates before granting access.
OAuth 2.0	OAuth 2.0 - OAuth (Open Authorization) is an authentication and authorization framework that allows applications to securely access resources on behalf of a user without exposing their credentials. It is commonly used for third-party API access, such as logging in with Google, Facebook, or GitHub. Grant Type - The grant type defines how the client application obtains an access token. Common grant types include. Select the Grant Type as Password Credentials or Client Credentials. Token URL - The Token URL is the endpoint where the client application sends authentication requests to obtain an access token. Client ID - The Client ID is a unique identifier assigned to the client application by the API provider. Client Secret - The Client Secret is a confidential key assigned to the client application, used along with the Client ID to authenticate requests. UserName - Used in Password Grant Type, where the user directly provides their credentials to obtain an access token. Password - Used in Password Grant Type, where the user directly provides their credentials to obtain an access token. Confirm Password - Confirm the password entered above. Scope - The Scope specifies the level of access granted to the client. It defines what the client can do with the API (e.g., read-only, write access, or admin privileges).

Params
Key	Specify a name for the Key.
Value Type	Choose the Value Type from the drop-down list. For example, Static or API
API	Choose the selected name for the API.
API Element	Specify the API Element from the drop-down list provided.
Value	Select the value field which gets enabled only when the Value Type is chosen as Static.
Description	Choose a brief description about the parameter.
Action	Choose the Action button if the configurations need to be deleted.

Header
Key	Specify a name for the Key
Value Type	Choose from the drop-down list to specify the Value Type. Example: Static or API.
API	Choose the selected name for the API.
API Element	Specify the API Element from the drop-down menu.
Value	Specify the value. This field gets enabled when the Value Type is set to Static.
Description	Give a brief description of the Headers.
Action	Choose the Action button if the configurations need to be deleted.

Body
Request Type	Specify the format of the Body form the drop-down menu. For example, Text, JSON, XML.

Response
Description	Specify the format of Response from the drop-down menu. For example, Text or JSON.

Configured API

The last section Configured API displays the list of Configured API with the following details.

Figure: Configured API

Field	Description
Action	Choose the icons for Actions related to the API. For example, Edit or Delete.
API Name	The name specified while creating the API is displayed here. For example, Get User ID, Post Message, Create Calendar.
API URL	The URL to update the action is specified here.
API Method	The API method that has been specified is displayed. For example, GET, POST, PUT etc.
Authentication Name	The Authentication name that has been specified is displayed. For example, OAuth.
Status	The status is displayed as Active or Inactive. The standard HTTP status codes are displayed to indicate whether the API request has been executed successfully or not. The following are the standard response codes: Successful Responses (200-299) Client Errors (400-499) Server Errors (500 - 599)

Was this article helpful?

What's Next

Manage API Configuration

Table of contents

Configure API
API Details
Configured API