TeamConnect RESTAPIs - Authentication - Mitratech Success Center

Authentication

TeamConnect API uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The below is the OAuth2 Authorization Code Flow between a User, TeamConnect (Application), and a Login or SSO Provider (Single Sign-On):

How does it work?

The user sends a request to the TeamConnect application to access a resource. TeamConnect needs to authenticate the user first.
TeamConnect redirects the user to the TC Login or SSO Provider (identity provider like Google, Okta, etc.) for authentication.
The SSO provider shows a login page to the user where they can enter their credentials (username and password).
After the user successfully logs in, the SSO provider authorizes the user's login request.
The SSO provider validates the login and checks whether the credentials are correct.
After validation, the SSO provider sends an authorization code back to TeamConnect. This code is a temporary token used to request an access token.
TeamConnect sends the authorization code to the SSO provider to exchange it for an access token.
The SSO provider validates the authorization code and returns an access token to TeamConnect. This token is used to make authorized API calls on behalf of the user.
TeamConnect uses the access token to make API calls to access protected resources or services.

How to obtain Access Token using OAuth 2.0 in Postman?

OAuth 2.0 provides two primary methods for obtaining access tokens: the Authorization Code Flow and the Client Credentials Flow.

Authorization Code Flow: It is designed for scenarios that require user authentication, allowing users to log in and grant applications access to their resources by exchanging an authorization code for an access token.
Client Credentials Flow: It is suited for server-to-server communications, enabling applications to directly request access tokens using their client ID and secret, without any user interaction. Both methods ensure secure access to APIs while effectively managing authentication and authorization.

Follow the below steps to generate a bearer token via Authorization Code Flow:

Steps	Screenshot/GIF for reference
1. Create a new collection, then select the "Authorization" option and choose "OAuth 2.0" from the dropdown.
2. Once selected, scroll down to the “Configure New Token” section and enter the below details: Token Name-> Give a token name as per your choice. Grant Type-> Select “Authorization Code” from the dropdown. Callback URL: This should match your registered redirect URI. Auth URL: Enter your authorization URL where users will be redirected to log in. For e.g: [your TC instance]/webservice/enterprise/oauth/authorize Access Token URL-> [your TC instance]/webservice/enterprise/oauth/token Client ID-> Enter the Unique client ID obtained from TeamConnect. (For more information, refer to Client Secret-> NA Scope: (Optional) Specify the scope you need for access. Client Authentication-> Select “Send as basic Auth header” from the dropdown.
3. After entering all of the information, scroll down and click the "Get New Access Token". You will be redirected to TeamConnect login to enter valid Username/Password to get the access token.

How to register an API Client and generate a unique API Client ID from TeamConnect?

Login to TeamConnect and open the Setup window.
Navigate to System Settings > API Client Settings Tab
Enter Name of the Client, Description, Homepage URL, Callback URL and click Add Items button to generate unique API Client ID to use in Postman

Follow the below steps to generate a bearer token via Client Credential:

Steps	Screenshot/GIF for reference
Create a new collection, then select the "Authorization" option and choose "OAuth 2.0" from the dropdown.
Once selected, scroll down to the “Configure New Token” section and enter the below details: Token Name-> Give a token name as per your choice. Grant Type-> Select “Client Credentials” from the dropdown. Access Token URL-> [your TC instance]/webservice/enterprise/oauth/token Client ID-> Enter your TeamConnect Username. Client Secret-> Enter your TeamConnect Password. Client Authentication-> Select “Send as basic Auth header” from the dropdown.
After entering all of the information, scroll down and click the "Get New Access Token" option to generate a new token and Save.

Step 2 - To use bearer token to make API calls.

Create a new GET request and select Authorization. Under this, select the Type as “Bearer” from the dropdown. Add the same token value by copying the current token from your new collection and click Save.
How to Save the Token to an Environment Variable? You can define variables in Postman environments and collections in order to simplify your requests by setting a value in one place and reference it in as many places as necessary. So you can create a variable for your Bearer Token value. Do this by editing your collection and going to the Variables tab to add a new variable, for example, “TCat_Admin” as shown in the screenshot.
While editing your collection, go to the Authorization tab to set a default authorization for all requests within your collection. You can set the Authorization Type for your collection to Bearer and set the Token value to be your defined variable. This will allow you to use the same authorization token for all of your requests within your collection.
To use the collection's default authorization method, you must set the Authorization Type to "Inherit auth from parent" for all requests within that collection. Doing this will allow you to not have to deal with adding the Authorization header manually on to each request. Note: Each request within the collection with the "Inherit auth from parent" authorization type selected will automatically populate the request with the proper headers for authorization if you have defined a default option for the collection like in the previous step.

Pagination and Filtering

To provide full functionality these REST APIs will come with pagination and filtering.

Pagination allows the API to return a subset of data, decreasing data transfer and increasing performance. Filtering allows users to filter down search results by specifying criteria.

Pagination

Pagination in a REST API breaks down large result sets into smaller sections (pages) and delivers them in separate requests. This helps manage response size and reduces data transfer over the network.

The client specifies a page number and the number of items per page in the request. The API returns the requested page, along with metadata indicating the total results. This approach optimizes network bandwidth and improves the efficiency of API requests.

Pagination format for data retrieval using a REST API is as follows:

GET /webservice/enterprise/v1/records/ACCT/page={number}&pageSize={number}

page={number}: This is a query parameter that specifies the page number of the data being requested. Pagination is used to break large sets of data into smaller, more manageable pieces. The {number} part is a placeholder where the actual page number will be inserted.

pageSize={number}: This query parameter defines how many records are returned per page. The {number} is a placeholder where the client will specify the number of records to retrieve in a single response.
Note: The default value is 200 records per page. It's recommended that clients always specify a pagesize to have more control over how many records are returned in a response, which can optimize performance based on the client’s requirements.

Example Query:

For a request with page number 3 and a page size of 20, the query would look like this:

GET /webservice/enterprise/v1/records/ACCT/page=3&pageSize=20

Filtering

Filtering in REST API is the process of limiting the results of an API request based on certain criteria.

Filtering enables customers of a REST API to obtain only the data they require, which can help to enhance API speed and limit the quantity of data delivered over the network.

Filter by using searchview, by search criteria:

You can filter records using two methods:

By search view

To filter records based on a predefined search view, use the searchViewKey query parameter to provide the unique key of a Search View when making a request to the GET /records/<unique code> endpoint. The default search qualifiers of the search view will be used to filter the search results.

By explicit search criteria

Use the POST /records/<unique code>/search endpoint to provide custom search criteria. In this case, you will need to provide your search criteria in the request body, formatted as JSON.

Errors

TeamConnect REST APIs use conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).

The following are the general status codes returned by the APIs:

Status	Message	Description
200	Ok	Request succeeded.
400	Bad Request	See response for details.
401	Unauthorized	System or User is not authorized to use the API.
403	Forbidden	Doesn't have permission to perform the request.
404	Not Found	The requested resource doesn't exist.

FAQs

How do I get the API token?
For more information to get API token, refer to How to obtain Access Token using OAuth 2.0 in Postman.
What format should the request and response data be in?
In JSON format.
What are the versioning policies for the API? How is API versioning managed?
When we introduce backward-incompatible changes to our APIs, a new version is released alongside a specific TeamConnect update. The latest public APIs are included in TeamConnect 7.2. If you need access to new APIs, please contact Mitratech to schedule an upgrade.
Is rate limiting implemented?
We have not implemented rate limiting at the application level.
Are webhooks supported?
Currently, webhooks are not implemented. If you're interested in this feature, please submit a request through AHA Idea portal.
How do I get support or report issues?
contact the Mitratech support team by sending an email to: support@mitratech.com.