Envase Gateway API Developer’s Guide

This guide provides information about how to integrate applications and services with Envase Connect Core API through the Envase Connect Gateway API. The Envase Connect Gateway API provides a single point of integration for all applications and services regardless of the TMS a customer is using or where that TMS is located. This allows client applications to use common code to integrate with all Envase TMS products.

Environments

The Envase Connect Gateway API is deployed to three separate environments created for different purposes. Depending on needs, clients will be enabled for a specific environment. The following environments are defined for Envase Connect Gateway API:

Development/Test

The development/test environment is for internal purposes. Internal Envase applications and services can request access to this environment during the early development process to insure their integrations work as expected. External applications and services are not allowed in this environment. The base URL for this environment is:

url:

https://core-dev.envaseconnect.cloud

Staging/Sandbox

This environment is used for testing features before they go into production, and for external or internal applications to test their code before going into production. If you are developing an external application or service, you can request access to this environment to insure your code works as expected prior to releasing your application or service.

The base URL for this environment is:

url:

https://core-stg.envaseconnect.cloud

Production

This environment is for production applications and services. Once your application or service is tested and ready for release you can request access to this environment. The base URL for this environment is:

url:

https://core.envaseconnect.cloud

Important

Each of the environment requires a different set of client id, secret and API key. You need to request them before attempting to access the environments. The client id and secret, as well as, the API key issued for one environment will not work on others. You can review the Authentication topic for more information.

Envase Core API Interface

The Envase Connect Core API interface exposes a common REST API that allows applications and services to interact with all Envase TMS products. This enables these applications and productions to use common code to interact with those TMS.

In order for this applications to communicate with the different TMS instances in a coherent way, the Envase Connect Gateway API was provided. All the http (https really) calls go through the Envase Connect Gateway API and this service forwards the call to the right TMS instance.

The Envase Connect Gateway API provides an additional layer of security due to the fact that all requests to the individual TMS need to pass Authentication. No direct communication between applications and services and the different TMS instances is allowed.

Still, the Envase Connect Gateway API does not manipulate the requests or responses from those applications and the TMS. It supports the exact interface known as Envase Connect Core API, which you can learn more about in the Envase Connect Core API Specification.

Authorization/Authentication

All requests require an Authorization token to be provided in the Authorization header as described in the Authentication topic. On top of that, every client application and service needs to request an API key unique to that client. This API key is issued by Envase and must be provided with every request in the X-Api-Key header.

The level of access of an individual client application or service is controlled by scopes. The registered clients will be assigned scopes according to their needs. These scopes will determine which APIs a specific client can invoke.

Another level of security is provided by the fact that every request must be sent on behalf of a user. The process of authentication/authorization requires a user to sign in, and the access token provided will contain information about the Identity of that user. Users have roles; therefore, individual users will have individual access privileges to the API.

Every client application or service must be prepared to handle return codes of 401 Unauthorized and 403 Forbidden in order to insure the application and service works properly. The application should then act appropriately when those codes are returned.

Additional Information

You can review the Envase Connect Core API documentation to learn more about how to interact with the different Envase TMS. The Envase Connect Core API Specification provides information about each of the endpoints exposed as public interface.

The Authentication topic discusses how authorized requests can be sent to Envase services, which applies to all calls to Envase Connect Gateway API.