ISM API Overview

The ISM APIs allow any authenticated client application to access ISM functionality outside of the ISM web application.

• The APIs are built using GraphQL, an open-source query language for APIs, and are exposed through a single endpoint that ends with /graphql.

• ISM Core APIs - These APIs expose core ISM capabilities, including class library and catalog management.

• All API requests are sent to the same endpoint and are routed and processed based on the content of the request body.

Authentication

Access Tokens for ISM APIs

This section describes the various Access Tokens that can be used to access the ISM APIs and how to create and configure these access tokens.

Supported Token types:

• Account Access Tokens

• Service Access Tokens

• Service Application Tokens

• User Access Tokens

  Notes:

• Only an Account Administrator can create Account, Service, and Service Application Tokens.

• Only CONNECT authenticated users who have ISM access can obtain User Access Tokens.

Procedure to create an Access Token:

1. Sign in to your account.

2. Navigate to Integrations.

3. Select Access Tokens.

4. Click Create Access Token.

   The Create Access Token page is displayed.

   

Procedure to configure Access Token

5. Enter the required details as described below:

• Description: Enter a meaningful description for the token. This helps in identifying the token later.

• Expiry Date: Displays the date when the token will expire. By default, the expiry date is set to one year from the creation date.

Configure an Access Token

6. Select Advanced. There are two options under Advanced:

• Account Access Token

  7. By default, the form creates Account Access Token, which allows access to account-level roles such as Administrator or SCIM. You can assign multiple roles as needed.

  8. Choose an Account Access Token when you need to grant access at an account-level.

  9. Select the appropriate role based on the level of access required.

     

• Service Access Token

  10. When ISM is configured as a service in your account, you can create or select a Service Access Token to provide access to specific ISM services.

  11. Select the service for which the token is used.

  12. Assign the appropriate role (such as Creator, Author, Reader, or Administrator) based on the level of access required.

      

  Note: Once the AAT, SAT is created, copy the token and save it as the tokens are not stored or available for copying at a later point.

• Service Applications Token

  13. In Integrations, click Service applications.

      

  14. Click Create service application.

      

  15. Select Service role and specify the relevant details.

  16. Click Create.

      

      The application displays the Client ID and Client Secret.

      

  17. Specify the required details in the body and headers.

  18. Send the request to get the service application token.

      

      

      The Service Application Token is obtained as a response.

• User Access Tokens

  This token can be fetched from ISM application launched via a browser by accessing the network tab and copying the token from the Authorization Header.

  

Authorization

API access is governed by the assigned user role and follows the existing ISM access control rules.

Supported Roles

• Reader

• Author

• Creator

• Administrator

API Operations

• Query – Read-only requests

Response Status Codes

• 200 OK – The request was processed successfully.

• 401 Unauthorized – The request lacks valid authentication credentials. The client must authenticate to access the resource.

• 403 Forbidden – The client is authenticated but does not have sufficient permissions to access the requested resource.

• 500 Internal Server Error – The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error returned when no more specific 5xx status code applies.

API Request Format

Endpoints

The ISM API endpoint follows the below standard pattern:

• For default stages, the endpoint is: https://<hostname>/api/graphql

• If the environment includes a shard, the endpoint becomes: https://<hostname>/<shard>/api/graphql

• Example:

  Given a hostname xyz.ism.connect.aveva.com:

  Default stage endpoint: https://xyz.ism.connect.aveva.com/api/graphql

  Shared Endpoint (for example shard s1): https://xyz.ism.connect.aveva.com/s1/api/graphql

Request

The ISM API request is configured as below in graphql clients:

• Method: Post

• Headers: Content-Type: application/json

• Authorization: Bearer <your_token>

• Body: raw → JSON and provide your API request.

• Example: Request for Catalog Collection