Envase Identity Manager Developer’s Guide
This guide provides information about the Envase Identity Manager API that applications and services can use to access user information. It also provides information on how Envase applications and services can use the API to manage their users. The Envase Identity Manager API specification documents all the endpoints supported, and it is provided for developers to understand the correct use of the API.
Environments
The Envase Identity Manager service is deployed to three different environments that allow us to test and verify the functionality before it is made available in production.
Using the Envase Identity Manager service requires your application to register a client as specified in the Authentication topic. The Envase Identity Manager service also requires that an API key is issued for your application. The Authentication topic explains how you should use your client id, client secret, and API key to send requests.
The following describes each of the environments:
Development/Test
This environment is used internally to verify the functionality before is made available to other teams. If you are an internal application and you have a development/test environment, you should point your service to this environment. The base URL for the environment is:
Staging/Sandbox
The staging/sandbox environment is provided to get features and APIs ready for release. We also use this environment to allow access to external applications to test their code before they go into production.
Warning
External applications and services will rarely need access to Envase Identity Manager. If you feel that you need access to the service, you can submit a request stating your use case.
The base URL for this environment is:
Production
This is the live production environment that all released applications and services should use. This is the environment you should use once your application or service is released. The base URL for production is:
Organizations API
The Organizations API is exposed for services and applications to manage their customer information, as well as, the registered TMS they use. Each organization has a unique identifier that should be used across Envase services and applications. At the same time, each of the TMS registered to an Organization has a unique identifier that can be used to refer to a specific TMS instance across all Envase applications and services.
The Organizations API is the main service exposed when creating new customer accounts, and each individual customer account will have its own Organization.
Like any other API in the Envase Identity Manager service, requests to the Organizations API need to be authentication. You can learn more about it in the Authentication topic.
Creating An Organization
Creating a new organization requires that the user logged in has a System Administrator role. Usually, support techs have this role, so they can create new organizations for new customers.
The API requires to use a POST request specifying the name of the organization.
POST https://core.envaseconnect.cloud/identity/organizations
The request payload must contain the Organization name.
{
"name": "My New Organization"
}
The response should return a status of 201 CREATED with the following body:
{
"id": "1d49b8c1-b988-4014-bf5b-bef304abc79b",
"self": "/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b"
"name": "My New Organization",
"tms": {
"id": "1d49b8c1-b988-4014-bf5b-bef304abc79b",
"href": "/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b/tms"
}
}
A new unique identifier for the organization is created. The relative URL to the organization information is also provided. As you can see, the specified name is also part of the response.
Information about the associated TMS instances is also provided. A request to the specified TMS URL will return a collection of all the TMS associated with the organization. Since you just created the organization, the collection will be empty.
You can find all the information about this API at the Envase Identity Manager API specification.
With a new organization create, you can now register a TMS instance with the organization.
Registering A New TMS
Registering a new TMS instance with an organization requires the user to have System Administrator or Organization Administrator privileges. As you saw above, creating a new organization returns the URL for the associated TMS collection. You will use this URL to associate/register a new TMS instance.
POST https://core.envaseconnect.cloud/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b/tms
You will use the Organization identifier as part of the URL to indicate the association. The request body requires the information about the new TMS.
{
"name": "My New TMS",
"type": "PROFITTOOLS",
"url": "https://tms.myorg.com"
}
A new TMS requies to specify a name, as well as the TMS type. It also requires to specify the URL where the Envase Connect Core API implementation service is located. Customers are required to provide the URL for their implementation for some of the TMS types. You can check the Technical Guide for more information about the TMS URLs.
The response from this API will have a status of 201 CREATED and will provide all the information about the registered TMS.
{
"id": "be4a9165-97a0-4740-bcf9-f8a3850b1418",
"self": "/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b/tms/be4a9165-97a0-4740-bcf9-f8a3850b1418",
"name": "My New TMS",
"type": "PROFITTOOLS",
"url": "https://tms.myorg.com"
}
As you can see, a unique identifier is created for the TMS and the relative URL to its information is provided, as well as the specified information to create it.
Registering a new TMS with an Organization requires to specify the TMS type. This identifies the specific Envase TMS product the organization is registering. The possible values for this property are:
COMPCARE: Indicates the associated TMS is a Compcare TMS.
ENVASE: Indicates the associated TMS is Envase TMS.
GTG: Indicates the associated TMS is a GTG TMS.
PROFITTOOLS: Indicates the associated TMS is a Profit Tools TMS.
Registering A New Service
Registering a new Service instance with an organization requires the user to have System Administrator or Organization Administrator privileges. As you saw above, creating a new organization returns the URL for the associated Service collection. You will use this URL to associate/register a new Service instance.
POST https://core.envaseconnect.cloud/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b/services
You will use the Organization identifier as part of the URL to indicate the association. The request body requires the information about the new Service.
{
"name": "My New Appointment Service",
"type": "APPOINTMENT",
"metadata":{
"url": "https://service.myorg.com"
}
}
A new Service requies to specify a name, as well as the Service type. It also requires to specify the metadata which can be used to add service related data in key/value format. Customers are required to provide the URL for their implementation for some of the Service types in metadata. You can check the Technical Guide for more information about the Service URLs.
The response from this API will have a status of 201 CREATED and will provide all the information about the registered Service.
{
"id": "be4a9165-97a0-4740-bcf9-f8a3850b1418",
"self": "/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b/services/be4a9165-97a0-4740-bcf9-f8a3850b1418",
"name": "My New Appointment Service",
"type": "APPOINTMENT",
"metadata":{
"url": "https://service.myorg.com"
}
}
As you can see, a unique identifier is created for the Service and the relative URL to its information is provided, as well as the specified information to create it.
Additional Organizations APIs
The Organizations API provides a full REST implementation. Using the different API, it allows applications to create, retrieve, update, and delete information about Organizations and associated TMS.
You can review the entire REST API in the Envase Identity Manager API specification.
Users API
The Users API allows applications and services to manage the information of individual users registered with Envase. It provides information about their user accounts, as well as, the Organization they belong, and the TMS they have access.
Users have roles that determine their level of access to other Envase services. Those access roles also control what the currently log in user can do within the Envase Identity Manager service.
Let’s see how a new user can be created.
Creating A New User
Creating a new User requires the current user to have a System Administrator or Organization Administrator role. System Administrators can create any new User account for any Organization. Organization Administrators can only create users as part of their own Organization.
The request to create a new user is as follows:
POST https://core.envaseconnect.cloud/identity/users
The body of the request must contain the following JSON:
{
"name": "John Smith",
"email": "jsmith@myorg.com",
"role": "ORG_ADMIN",
"organizationId": "1d49b8c1-b988-4014-bf5b-bef304abc79b"
}
A name for the user must be specified. Also, an email for the user is required. This email will be used for the user to log in. It is also required to specify a role for the user.
Organization Users require the organization identifier to be specified to associate the user with an organization. Some users might not belong to an organization; therefore, the parameters is optional.
Warning
Although possible, it is rare that new user doesn’t belong to an Organization. The most common scenario is for System Administrators because they are Envase employees. A rare exception is for freelance drivers using the Envase Mobile App who might work with multiple Organizations and have access to multiple TMS. Keep this in mind when creating a new user.
The response from this API will be 201 CREATED, and the response body will look similar to the following:
{
"id": "b746d763-6666-4002-b7bb-b76f8052f4e5",
"self": "/identity/users/b746d763-6666-4002-b7bb-b76f8052f4e5",
"name": "John Smith",
"email": "jsmith@myorg.com",
"role": "ORG_ADMIN",
"organizationId": "1d49b8c1-b988-4014-bf5b-bef304abc79b",
"tms": {
"id": "b746d763-6666-4002-b7bb-b76f8052f4e5",
"href": "/identity/users/b746d763-6666-4002-b7bb-b76f8052f4e5/tms"
},
"organization": {
"id": "1d49b8c1-b988-4014-bf5b-bef304abc79b",
"href": "/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b"
}
}
As you can see, a unique identifier is created for the User. The response also provides the User information and the relative URL to where the information for the user can be managed.
The response contains information about the registered TMS and Organization for the user if the user is an Organization User.
Same as with the organizations service, the collection of associated TMS will be empty when the user is created. You can associate a user with an existing TMS using the information provided.
Creating a new User requires a role to be specified for that user. Currently, these are the role types supported:
USER: This role indicates a standard user who normally is an employee of an organization.
DRIVER: This role indicates a standard driver for an organization. Drivers are usually employees of the organization.(deprecated)
CARRIER: This role indicates a user who is employee of a carrier organization. Carrier organizations do not have their own TMS but they might work for other Organizations that have registered TMS instances.(deprecated)
OWNER_OPERATOR: This are freelance users of the Envase Mobile App who do not belong to any specific organization, but they may get access to multiple TMS.(deprecated)
ORG_ADMIN: This role indicates users that manage the registered TMS and Users for their Organization. They have access to most of the Envase Identity Manager service APIs with restriction to their own Organization.
SYS_ADMIN: This role represent internal Envase employees that can manage all user accounts, organizations and TMS.
Once you create a user account, you will want to associate the account with a TMS.
Associating Users to TMS
You can associate a User with a TMS by sending a request to the user TMS service. The relative URL for this API is provided when creating a new user:
POST https://core.envaseconnect.cloud/identity/users/b746d763-6666-4002-b7bb-b76f8052f4e5/tms"
The URL requires the unique identifier for the user provided when the user was created.
The body of the request looks like the following:
{
"serviceId": "be4a9165-97a0-4740-bcf9-f8a3850b1418",
"metadata": {
"internalId": "100235"
}
}
The request requires to specify the unique identifier of the TMS, as well as the role for the User within the TMS. This role overwrites the permissions specified in the user account if different. This allows users to be Organization Administrators in some TMS, but standard Users in others.
Each TMS instance is probably keeping their own user lists with their own unique identifiers. In order to associate the user within a TMS the internal id within the TMS needs to be provided.
Assuming the user above was associated with a PROFITTOOLS instance, the information specified indicates that the user is associated with the driver in Profit Tools with an id of 100235.
Associating Users to Service
You can associate a User with a Service by sending a request to the user Service. The relative URL for this API is provided when creating a new user:
POST https://core.envaseconnect.cloud/identity/users/b746d763-6666-4002-b7bb-b76f8052f4e5/services"
The URL requires the unique identifier for the user provided when the user was created.
The body of the request looks like the following:
{
"serviceId": "be4a9165-97a0-4740-bcf9-f8a3850b1418",
"metadata": {
"internalId": "100235"
}
}
The request requires to specify the unique identifier of the Service, as well as the role for the User within the Service.
Each Service instance is probably keeping their own user lists with their own unique identifiers. In order to associate the user within a Service the internal id within the Service needs to be provided.
Assuming the user above was associated with a PROFITTOOLS instance, the information specified indicates that the user is associated in Profit Tools with an id of 100235.
Additional Users APIs
The Users API provides a full REST implementation. Using the different API, it allows applications to create, retrieve, update, and delete information about Users and their associated TMS.
You can review the entire REST API in the Envase Identity Manager API specification.
Additional Information
The following sections describe useful information to consider when implementing applications that use Envase Identity Manager.
Creating New Accounts
Envase provides an admin portal that allows System Administrators to create new accounts for new customers. All the operations necessary to create new accounts are exposed through the different APIs in Envase Identity Manager, but to simplify the implementation of the admin portal, an additional API was provided. This API can only be accessed by System Administrators.
POST https://core.envaseconnect.cloud/identity/accounts
The request requires the following JSON information:
{
"organizationName": "My Organization Account",
"tmsName": "My Organization TMS",
"tmsType": "PROFITTOOLS",
"tmsUrl": "https://api.myorg.com",
"adminName": "John Smith",
"adminEmail": "jsmith@myorg.com"
}
This API requires all the information for an Organization, a default TMS, and an initial Organization Administrator account. The API will first create a new Organization with the specified information. Then, it will create an associated TMS within the Organization. Also, it will create a new Organization Administrator account for the specified user and associate the created TMS with that user.
Basically, this API performs all the operations described in this guide with the caveat that only System Administrators have access to this API.
The response from this API looks like follows:
{
"id": "1d49b8c1-b988-4014-bf5b-bef304abc79b",
"self": "/identity/accounts/1d49b8c1-b988-4014-bf5b-bef304abc79b",
"organization": {
"name": "My Organization Account",
"id": "1d49b8c1-b988-4014-bf5b-bef304abc79b",
"href": "/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b"
},
"tms": {
"id": "1d49b8c1-b988-4014-bf5b-bef304abc79b",
"name": "My Organization TMS",
"href": "/identity/organizations/1d49b8c1-b988-4014-bf5b-bef304abc79b/tms/be4a9165-97a0-4740-bcf9-f8a3850b1418"
},
"user": {
"id": "b746d763-6666-4002-b7bb-b76f8052f4e5",
"href": "/identity/users/b746d763-6666-4002-b7bb-b76f8052f4e5",
"cognitoId": "b746d763-6666-4002-b7bb-b76f8052f4e5",
"name": "John Smith",
"email": "jsmith@myorg.com",
"role": "ORG_ADMIN",
"organizationId": "1d49b8c1-b988-4014-bf5b-bef304abc79b"
}
}
The response status will be 201 CREATED, and all the information about the created entities is provided in the body of the response.
User Permissions
The full REST API implementation of Envase Identity Manager can be divided into read APIs and write APIs. System Administrators have access to all the APIs exposed by the Envase Identity Manager service. Organization Administrators also have access to all the APIs, but the operations can only work within their organization.
An Organization Administrator can retrieve information about all Users, but only the Users associated with their own Organization will be returned. In the same way, they can update and delete information about any of the entities related to their Organization, but they don’t have access to other Organizations information.
All other users, only have read privileges to their own information. They can pull Organization and TMS information, but only if they have been associated with those entities.
Invitation Emails
When new User accounts are created, the User will receive an invitation email at the email address specified. The email contains a temporary password that must be changed during first log in.
The invitation email also contains a link that allows the user to log with the temporary password and change it. This link is only available for a reduced period of time; therefore, all users need to confirm their account by log in into the service and changing the password.
Service Accounts
The Envase Identity Manager service supports the concept of a Service Account. This type of accounts are used for internal purposes only where an Envase service needs to use the Envase Identity Manager API. These Service Accounts are really special internal clients with Client Credentials authentication, and will only be issued for internal services.
Important
Under no circumstances, a service account will be provided to external applications and services. Service Accounts have the same privileges as System Administrators within Envase Identity Manager, and they allow access to all the information about Organizations, TMS, and Users.
These accounts can access all the information in Envase Identity Manager, so they need to be approved for internal purposes.