Request a Demo

Cognosos API Overview

API Authentication
Rest API
GraphQL API

Overview

Cognosos offers a rich set of APIs to facilitate secure, accurate, and fast data exchange between the Cognosos RTLS and customers’ systems.

This document provides an overview of Cognosos APIs for logistics customers (FVL, Auto Auction, Yard Management). Configuration of the APIs (requirements, customer needs) are determined between the customer and the Customer Success team.

  1. REST API used for Cognosos applications and customers; primary API used for pulling data
  2. GraphQL Event Subscription API used to subscribe to specific events

Apart from authentication, there is no overlap between the two APIs. You will need to run the authentication process as the first step of the configuration process.

Any API-based program or platform can integrate with the Cognosos APIs to:

  • Streamline operations for more efficient workflow
  • Integrate Cognosos functions/features to improve the user experience
  • Automate tasks such as detaching/attaching assets from/to tags
  • Set up checks for assets located in outbound zones/areas
  • Review inventory holds and query for assets
  • Run asset and tag status checks
  • Subscribe to location adjustments or updates

API Authentication

Authentication takes place using OAuth2. The authentication process is required for new client installations and may be necessary to proactively renew tokens before expiration or to refresh a token if there is a renew on failure (401 error). Use this process to authenticate any of the APIs.

Before using REST or GraphQL APIs, generate a bearer token for accessing API endpoints using the following steps. Link to swagger doc here: https://docs.cognosos.net/.

Step one

Retrieve configuration from the /config endpoint with the category parameter set to idp. Use the curl request: GET ‘https://api.cognosos.net/config’. This is an unauthenticated API used to retrieve API configuration values.

Example configuration response:

Save the values for the client_id and issuer_url.

Step three

Use the value of the IdToken in the POST response as the Bearer token in the Authorization header when making API requests.

Step two

Use the client_id and issuer_id values from the config API to authenticate and receive a token.

Example using curl to retrieve the token:

				
					curl -s --request POST \ 
--header "Content-Type: application/x-amz-json-1.1" \ 
--header "X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth" \ 
--data "{ 
"AuthFlow": "USER_PASSWORD_AUTH", 
"ClientId": "$CLIENT_ID", 
"AuthParameters": { 
"USERNAME": "$LOGIN", "PASSWORD": 
"$PASSWORD" 
}}" $ISSUER_URL

 Example authentication response:

				
						{
  "AuthenticationResult": {
    "AccessToken": "eyJraW…DL9lg",
    "ExpiresIn": 3600,
    "IdToken": "eyJraW…mrDbw",
    "RefreshToken": "eyJjdH…clBw",
    "TokenType": "Bearer"
  },
  "ChallengeParameters":

Rest API

The REST API is the primary API, providing a comprehensive set of options that can be used for the portal UI, mobile apps, and for any client to pull data to/from the Cognosos system (e.g., applications, devices, custom fields, events, etc.), as well as make changes to the platform.

Link to Swagger docs:  https://docs.cognosos.net/ to view all API options and to make configuration changes.

At the minimum, most logistics clients should use the node attach, node detach, and node batch save (for custom fields) APIs. The Customer Success teams partner with customers to determine other API integrations.

GraphQL API

The GraphQL API refers to the https endpoints for querying events that need to be pushed from the Cognosos system to the client’s system (e.g., location adjustment). This method is especially useful for querying events such as zone changes, asset relocations, battery updates, and more. Please contact your Customer Success representative for additional support if needed.

Go to https://graphql.cognosos.net/graphql. Select Fields under Subscription.

Set up a subscription for each event that the client system should push an event request for to the Cognosos system. Refer to the samples at the end of this document for GraphQL event subscription examples.

Refer to the GraphQL confluence document for testing various GraphQL endpoints and using Postman to set up test subscriptions.

Scroll to Top