iCONECT API Documentation 0.11.0 (v1)

The iCONECT API allows developers to work with objects in iCONECT, including advanced functionality like managing clients, projects, records and files, using OpenID Connect authentication. This API uses common RESTful verbs, like GET, POST, PUT, and DELETE requests with JSON arguments and responses. Use this documentation to start making API calls.

The iCONECT API is a set of stateless services that uses endpoints to manage the following objects:

• Clients: create, manage, and retrieve project association
• Projects: create, manage, assign to a client and retrieve client association
• Fields: create and manage fields in a project
• Panels: create and manage panels in a project
• Folders: create, manage, and assign to panels or parent folders
• Records: create, manage, and assign to folders
• Upload native files: manage the files linked to a record
• Jobs: manage jobs in a project
• Views: create and manage views in a project
• File Stores: access file stores in a project
• Templates: access templates in a project

Use these notes to review the latest iCONECT API and documentation updates. This section lists API operations and fields that were added, changed, or removed.

New Features and Updates

• Enhanced request and response payload documentation for all endpoints.

Modified or Updated Endpoints

• Add Records to Folder: The request body of this payload has been changed to accept an array of record IDs.
• Remove Records from Folder: The request body of this payload has been changed to accept an array of record IDs.

Bug Fixes

• Corrected a missing scope parameter for the Authorization Code Grant and Password Credentials Grant sections.
• Corrected erroneous request and response payloads in Records, Folders, Panels, and Fields endpoints.

New Features and Updates

• The REST API is now running on ASP.NET Core 6.0.
• Documentation is now automatically updated with each build.
• The REST API now authenticates with the iCONECT Identity Provider using OpenID Connect.

Breaking Changes

• Authorization Code Grant: This URI has been changed from {iconectURL}/oauth/authorize to https://{identityURL}/openid/authorize.
• Password Credentials Grant: This URI has been changed from {iconectURL}/oauth/authorize to https://{identityURL}/openid/token.
• Password Credentials Grant: A Client ID is now required when using this grant type.
• Refresh Code Grant: This URI has been changed from {apiURL}/oauth/authorize to https://{identityURL}/openid/token.
• Authorization: The iconect_api scope is now required.

Modified or Updated Endpoints

• Authorization: The REST API now uses OpenID Connect for authentication and authorization. The API access tokens are now in the form of a JSON Web Token (JWT) that is signed by the primary web UI instance.
• Authorization: Password Grant will no longer issue a refresh token. It is advised to transition any Password Grant flows to different authentication.

Bug Fixes

• Folders by ID: Added missing documentation for this endpoint.
• Record Count: Added missing documentation for this endpoint.
• Folders for Record: Added missing documentation for this endpoint.
• Multiple corrections to the naming of enums, including brief descriptions of each value.

New Endpoints

• Upload Target: Retrieves the project ID that has been configured in iCONECT for uploading data to.

Modified or Updated Endpoints

• File Store Upload: The File Stores endpoint now supports functionality to upload files directly.
• Authorization: Password Credentials Grant now issues a refresh token. See the Password Credentials Grant section for more details.
• Create Records:
  • The Create Records endpoint now additionally supports adding references to Amazon S3 Buckets as native files.
  • The Create Records endpoint now returns more detailed error reporting.
• Update Records: The Update Records endpoint now additionally supports adding references to Amazon S3 Buckets as native files.

Bug Fixes

• Fixed an issue in the Password Credentials Grant flow where access token expires_in would differ from the actual token life time.

New Endpoints

• User: Access information about the authorized user
• Project - Project Settings: Access metadata about the settings configured for a project
• System Information: Access information about the iCONECT system and REST API

Modified or Updated Endpoints

• Authorization: Proof Key for Code Exchange (PKCE) is now required when using the Authorization Code flow.

Bug Fixes

• Fixed an issue in File Upload where users would not be able to upload a file in some cases.

• This version did not have any API interface changes

New Endpoints

• Templates: Access Native Import template objects in a project

Modified or Updated Endpoints

• Jobs: Supported job types now include Native Imports
• Records - List: Records List can now optionally accept a View ID
• File - Upload: Improved performance when uploading a file in a single request (or chunk)

New Endpoints

• Views: create and manage views in a project

Modified or Updated Endpoints

• Jobs: Supported job types now include Delete Records
• Jobs: The start job endpoint has been modified to accept a request body when starting a Delete Records job Start Job
• Authorization: Support for OAuth Password Credentials Grants is now supported. See the Password Credentials Grant section for more details.

Modified or Updated Endpoints

• Error handling for the update records endpoint was adjusted. If there is an issue on one record passed in, all other records will still be updated. A 200 response will be returned along with an array that lists the specific records that could not be updated: Records - Update

New Endpoints

• Jobs: manage jobs in a project
• File Stores: access file store objects in a project

Modified or Updated Endpoints

• The endpoint to upload a file now includes support for large files, with the ability to use chunked uploads. This endpoint now also requires the set up of a Native File Upload File Store for the project. See File - Upload
• Error handling for the update records endpoint was adjusted. If there is an issue on one record passed in, all other records will still be updated. The returned error will contain information for every failure that happened during the update: Records - Update

Bug Fixes

• Requests with the content type application/json; charset=utf-8 are now permitted

New Features and Updates

• This iCONECT REST API is in a new format .
• All endpoints return more specific codes. See Response Codes for details.
• Endpoints that query objects by ID now return 404 - Not found code when the object doesn't exist
• Authorization_code flow was introduced to the OAuth authentication replacing the password flow from Beta 1. See the Authorization section for more details on how the access and refresh token is retrieved.

New Endpoints

• Project - Update: changes a project’s name and description
• Fields - Delete: deletes fields in a project
• Fields by ID: retrieves Fields by ID
• Records - Update: Updates records in batches

Modified or Updated Endpoints

• The endpoint to deactivate a Client is renamed to /clients/:id/deactivate: Client - Deactivate
• The endpoint to deactivate a Project is renamed to /projects/:id/deactivate: Project - Deactivate
• The project list endpoint now allows filtering projects and templates. See Project List for more details
• Null and empty fields are now handled and validated when creating or updating records: Records - Update
• Files: parameters are now provided in the path. Only the file parameter should be provided in the body of the request: See Files for details.

Bug Fixes

• The Panel location property description was updated to the correct enum: Panel - Create
• The create records endpoint now returns all successfully create records: Records - Create
• Fixed an issue where querying a record by ID returned a list instead of a single record
• Fixed an issue where querying an empty folder returned records
• Fixed an issue where querying a folder by ID returned a list instead of a single folder
• Fixed an issue where updating multiple records that contained an invalid record could cause a failure to update all records

The material in this document is the sole and exclusive intellectual property or iCONECT Development, LLC and/or iCONECT Worldwide Inc. Collectively (“iCONECT”). ICONECT believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided “as is”. ICONECT makes no representation or warranties of any kind with respect to the information in this publication and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Using, copying, and distribution of any ICONECT software described in this publication requires an applicable software license which is available by contacting info@iconect.com .

The information in this document is provided for use with ICONECT products. No licence, express or implied, to any intellectual property associated with this document or such products is granted by this document.

All ICONECT products described in this document are owned by ICONECT (or those companies that have licensed technology to ICONECT) and are protected by patents, trade secrets, copyrights or other industrial property rights worldwide.

The ICONECT products described in this document may still be in development. The final form of each product and release date thereof is at the sole and absolute discretion of ICONECT. Your purchase, license and/or use of ICONECT products shall be subject to ICONECT’s then current sales terms and conditions.

Downloading and/or use of any component herein confirms your agreement with these Terms of Use and you agree to be bound by these Terms of Use without signature.

If you need more information about using the iCONECT API, contact iCONECT Support at (855) 915-8888 (non-US +1 519-645-6190) or email support@iconect.com.

The iCONECT API uses standard REST response status codes to indicate the success or failure of the calls.

The body of the response will be JSON in the following format for errors:

  { "iconect_error": "message" }

And for success codes:

  { "iconect_ok": "message" } 

The response code will be included in the header of the response and can be one of the following:

The iCONECT Rest API supports OpenID Connect authenication and authorization.

The authorization code grant permits external application access to the API, which acts on behalf of the authorizing user and is the recommended flow. An external application must be registered with iCONECT before it can use OpenID Connect to authenticate users using the authorization code grant.

The password credentials grant is only recommended when a single user will act on behalf of a 3rd party application.

Administrators can create, and Users need to authorize access of external applications to the API. Before this can be done you need to ensure the external applications are authorized to access the API. You can revoke the access to the authorized application at any time.

Authorizing via OIDC requires the following steps:

1. Create the application in iCONECT
   • Register for a new application. Log into iCONECT using your Administrator account.
   • Open Administration. The application menu will be displayed in the left sidebar.
   • Click New Application. This button can be found in the top right corner of the page.
   • Enter the name of the application and its redirect URI. If this application is a web UI, consider adding a Logout Redirect URI. Click Create.
   • Once the application is created go to the Application page and click on its name to get the client ID and client secret key.
2. Get authorization from the user
3. Retrieve the access code and token
4. Make Authenticated Requests with the token

Obtaining an Authentication Code

The application accessing the Rest API needs to be registered on iCONECT v10. Administrators can provide the client_id and client_secret to the external application after it is created in iCONECT.

The external application can obtain an access code (to get the access token) sending a GET request to:

https://{identityURL}/openid/authorize

Once completed, an iCONECT authorization page displays. If the external application is authorized, iCONECT sends the authorization code to the redirect_uri.

Getting Access Token with Authentication Code

The external application can request an access token using the code obtained from the https://{identityURL}/openid/authorize endpoint along with the other parameters provided, sending a POST request to:

https://{identityURL}/openid/token

If the response is successful, you are returned with a JSON string that contains the access, refresh tokens, and the expiry time in seconds.

Note: Once a refresh token has been used to acquire a new access token, it is considered to be consumed and is no longer valid.\

{
     'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
     'token_type': 'bearer',
     'expires_in': 3559,
     'refresh_token': 't3f389yhf93h28f38fg239rf3g2f9823hf23fh2398f4'
}

The external application can obtain access to the Rest API points using the token provided.

Getting Access Token with Refresh Token

The external application can request the access token using the refresh_token obtained from the https://{identityURL}/openid/token endpoint along with the other parameters provided, sending a POST request to:

https://{identityURL}/openid/token

If the response is successful, you are returned with a a JSON string that contains the access, refresh tokens, and the expiry time in seconds:

{
     'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
     'token_type': 'bearer',
     'expires_in': 3559
}

The external application can obtain access to the Rest API points using the token provided.

Authorization flow

1. Request authorization code

To request the authorization code, redirect the user to the https://{identityURL}/openid/authorize endpoint with the following GET parameters:

https://{identityURL}/openid/authorize?
    client_id=APP_ID&
    redirect_uri=REDIRECT_URI&
    response_type=code&
    state=YOUR_UNIQUE_STATE_HASH
    code_challenge=YOUR_UNIQUELY_GENERATED_HASH
    code_challenge_method=S256&
    grant_type=client_credential&
    scope=iconect_api%20openid
        

This will open the iCONECT login page to approve the application's access to their account and then redirect back to REDIRECT_URI that you provided. The redirect will includes a code parameter. For example if the REDIRECT_URI is https://mywebapp.com/oauth/redirect then the redirected URL will be:

https://mywebapp.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH

Use this code to request an access token. Note that: https is required and the REDIRECT_URI given in the request must be the same as the URI that is used when registering the application. For example https://mywebapp.com is not the same as https://mywebapp.com/ do not match because there is an extra \.

2. Request access token with authorization code

Once you have the authorization code you can request an access_token using any HTTP client. In the following example, we are using Java's Unirest library:

HttpResponse<String> response = Unirest.post("https://{identityURL}/openid/token")
.header("Content-Type", "application/x-www-form-urlencoded")
.field("client_id", "{client_id}")
.field("code", "{code}")
.field("redirect_uri", "{wwww}")
.field("grant_type", "client_credentials")
.field("code_verifier", "{pkce_code_verifier}")
.field("scope", "iconect_api openid")
.asString();

Example response:

{
   'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
   'token_type': 'bearer',
   'expires_in': 7200,
   'refresh_token': 't3f389yhf93h28f38fg239rf3g2f9823hf23fh2398f4'
}

3. Request access token with refresh token

Since the access token is set to expire you can request for a new access token using the refresh_token using any HTTP client. In the following example, we are using Java's Unirest library:

HttpResponse<String> response = Unirest.post("https://{identityURL}/openid/token")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .field("client_id", "{client_id}")
    .field("refresh_token", "{refresh_token}")
    .field("grant_type", "refresh_token")
    .asString();

Example response:

{
    'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
    'token_type': 'bearer',
    'expires_in': 3559
}

The Password Credentials Grant allows a 3rd party application to authenticate by providing the username and password for a single user that will perform all API Actions. An OAuth request is made providing the credentials.

A single request is made to obtain an access token which is then used as a bearer token for further requests.

In the following example, we are using Java's Unirest library:

HttpResponse<String> response = Unirest.post("https://{identityURL}/openid/token")
.header("Content-Type", "application/x-www-form-urlencoded")
.field("grant_type", "password")
.field("username", "jsmith")
.field("password", "Password1234")
.field("client_id", "{client_id}")
.field("scope", "iconect_api openid")
.asString();

Example response:

{
    'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
    'token_type': 'bearer',
    'expires_in': 3559,
    'refresh_token': 't3f389yhf93h28f38fg239rf3g2f9823hf23fh2398f4'
}

Endpoints to manage data servers in iCONECT.

Endpoints to manage file stores in a project.

Endpoints to manage the files linked to a record in a project

Endpoints to initiate a delete records, native import, delimited import, or zip file extraction job. Delimited import and zip file extraction jobs are used for processed imports in a project.

Endpoints to manage the records in a project