Authentication
You'll need to authenticate your requests to access any of the endpoints in the Envoy One API. In this guide, we'll look at how authentication works.
The only supported method of authentication is using the authorization code grant of the OAuth 2.0 specification. Additionally, PKCE is required as part of the authorization code flow. A guide on how the authorization code with PKCE works and how it can be implemented can be found here.
You will need to register an application to receive credentials for use in authorization, this can be done from the API page on the Envoy Dashboard.
All endpoints require authentication unless specified in the documentation, and all requests must be sent using HTTPS.
Once authorized, requests gan be made to the endpoints available to the requested scopes by passing the bearer token in the Authorization header.
Here's how to add the token to the request header using cURL:
Example request for listing customers
curl https://api.envoy.one/customers \
-H "Authorization: Bearer {token}"
Important: Always keep your credentials safe and reset it if you suspect it has been compromised.
HTTP Authentication
Scheme: bearer
The user's JWT access token as issued by the authentication service.
OAuth2 Authentication
-
Flow: Authorization Code
- Authorization URL: https://auth.envoy.one/oauth2/authorize
- Token URL: https://auth.envoy.one/oauth2/token
- Refresh URL: https://auth.envoy.one/oauth2/token
| Scope | Scope Description |
|---|---|
platform:admin | Ability to carry out administrative tasks against organisations and linked resources. |
locations:read | Read access to locations in the organisation. |
locations:admin | View & Manage locations and their configurations across the organisation. |
inventory:read | Read access to inventory items and location levels. |
inventory:manage | View & Manage inventory levels across the organisation. |
inventory:admin | View & Manage inventory items and corresponding levels. |
products:read | Read access to products and associated information. |
products:admin | View & Manage products across the organisation. |
orders:read | Read access to orders and associated resources. |
orders:admin | View & Manage orders and associated resources. |
shipments:read | Read access to shipments and associated resources. |
shipments:admin | View & Manage shipments and associated resources. |
shipments:create | Read existing shipments & create new shipments. |
Access Permissions
We use two forms of permissions to provide granular access:
- Scopes
- Roles
By combining these two forms of permissioning, it is possible to provide granular access to resources depending on the user's role in an organisation.
Scopes
As taken from the OAuth2 Specification, a scope is defined as follows:
Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.
We use scopes as described above. A client application requests a set of scopes for a user, and the user grants or denies access accordingly. In the event that the client application tries to access an endpoint that they do not have the necessary scope to access, a 403 error response is returned.
Roles & Abilities
To provide further granularity in what permissions a user has for accessing a given resource, each user account also has one or more roles associated with it. Roles can be thought of as a set of abilities, which in turn determine what data a user can access for a given endpoint.
For example, a user with the role owner might request the data for a customer, and receive all information associated with the customer, including the unique identifier, name, email address and postal addresses. A different user that has the reporting role then requests the same customer, but only receives the unique identifier and name, as their role does not grant them access to personal customer information.
Internal Scopes
The following scopes also exist, but must be whitelisted for access for a given client and user:
platform:internal_endpoints