Getting Started

This guide explains how to start developing client applications to Create, Read, Update, and Delete (CRUD) the Assent Compliance Entities data.

Infrastructure Requirements

• Company Account: Before using the Standard API, your company must have access to an ASM (Assent Sustainability Manager) application, which means that you must have an Assent account.
• User Account: Before connecting to the Standard API, you must have a valid, active user in the ASM. When connecting to the API, you must provide the email address of this active user. This ASM user account MUST have the "Data Importer" permissions enabled.
• UAT vs. Production: Every customer has two environments: the UAT environment used for integration development & testing, and the production environment. You use two different URLs when connecting to these environments, known as your BaseUrl:
  • https://standardapi.uat.assentcompliance.com:9193/
  • https://standardapi.assentcompliance.com:9193/
• Making Requests: The Assent API is a collection of RESTful Service Endpoints. All requests are made via standard HTTP Requests (GET, POST, PUT, DELETE) on port 9193. The body of those requests are in JSON format.
• Secure Sessions: When using the API, a secure session must be started. When starting a session, an authorization token (also known as a "JSON Web Token" or "JWT") is generated using the customer's API key and a valid user contact. This token is then used in the Authorization header for subsequent REST calls. Each call uses the bearer token to validate the caller's IP and contact email address.

Step 1: Get an API Key

• Contact your Assent Account Representative and let them know you are interested in accessing the Assent Compliance Entities via the Assent Compliance Standard API.
• The following information is required to generate an API key.
  • Your ASM: You must indicate which ASM you are trying to access via the API, your production or test environment.
  • IP Address: For security reasons, you must provide the IP Address of the server from which API calls will be made. The API Key will be tied to these IP Addresses, so that only calls originating from the registered IP Address can connect to the API.
    • Single IP Address
    • Multiple IP Addresses
    • Subnet Range - specified in IPv4 CIDR notation
    • Note: In order to allow any IP Address to connect to the API, use 0.0.0.0/0. This is not recommended but is conditionally allowed for UAT environments

• Expected Result

  • Your Assent Account Representative will provide you with a GUID to be used as your API key, for example: B27431C4-CDC3-4CAF-C11D-72AC9191762C.

Step 2: Confirm Connectivity

• Open Postman or another HTTP request tool
• Prepare a GET message to {BaseUrl}/healthcheck

• Expected Result

  • StatusCode 200
  • Current Server TimeStamp

Step 3: Request a JSON Web Token (JWT)

• Prepare a POST message to {BaseUrl}/sessions with the following JSON body:

  {
      "CompanyName": "My Company's Name",
      "ContactName": "The full name of the primary technical contact",
      "ContactEmail": "A valid email address of the user making the call",
      "ApiKey": "B27431C4-CDC3-4CAF-C11D-72AC9191762C",
      "Version": 7
  }
  

• Expected Result

  • The JSON body of the result message should contain a JWT:

    {
        "Token": 
                "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJDb21wYW55TmFtZSI6Ik15IENvbXBhbnkncyBOYW1lIiwiSG9zdE5hbWUiOiJlbnZpcm9ubWVudCBkZXBlbmRhbnQiLCJDb250YWN0TmFtZSI6IlRoZSBmdWxsIG5hbWUgb2YgdGhlIHByaW1hcnkgdGVjaG5pY2FsIGNvbnRhY3QiLCJDb250YWN0RW1haWwiOiJBIHZhbGlkIGVtYWlsIGFkZHJlc3Mgb2YgdGhlIHVzZXIgbWFraW5nIHRoZSBjYWxsIiwiRGVzY3JpcHRpb24iOiJTdGFuZGFyZCBLZXkiLCJFeHBpcmVzIjoiL0RhdGUoMTU4NTA3NDM3OTUyOSkvIiwiQXNzZW50Q29udGV4dCI6ImMxNmE0MzlkLWU2MmQtNDdiYi04MWIxLWZmOWUxYjdhYzE0NSIsIklwQWRkcmVzcyI6Ijo6MSIsIlZlcnNpb24iOjd9.fPgN7wHw0o8wV2sCJP2WD4u3e-41N4vMGCl5rIzDXzI"
    }
    

  • Your client will need to persist the JWT for use in all secured¹ Assent API endpoints.

Step 4: Your First READ Query

• Prepare a GET request message to {BaseUrl}/api/parts/supplierPartId. We're going to fetch supplier part id 1 in our example.

• The Header must contain a "Authorization" key with value "Bearer " + "YOUR JWT VALUE":

  

Expected Result

• SupplierPartId 1 returned with it's details, as described here.

  

Step 5: Using READ Filters

• Prepare a GET request message to {BaseUrl}/api/parts?PartRole=Product

  • Filters can be appended with &. This is an AND filter.
    (e.g. ?supplierNumber=289&datecreated>=2019-08-10&status=checked&offset=1000)
  • Supported operators: =, !=, >, <,>=, <=
  • Query parameters must be URL encoded i.e. john@doe.com -> john%40doe.com