Types of authentication

All apps must authenticate using OAuth 2 in order to use the API, however, the grant type will vary based on the type of app you are building.

• Private apps - can use the password flow grant or Client API Key
• Public apps - must use either client credentials or authorization code flow

Before we go into details of the authorization process here are a couple of concepts you should be familiar with:

• Client - Any app that wants access to a shop’s data. A user must grant permission before the client can access any data.
• API - Envoy REST API, which the client can use to read and modify shop data.
• User - A user of the account, usually an admin. The user gives permission to a client to access the company's data through the REST API.

Authorization flow for private apps

To authenticate a private app, you need to create an app to generate a client id and secret from the Dev Dashboard. You'll provide your username and password along with your client credentials in an authorization request to get back an access token that can be used to make requests to the API. You can view our authentication guide for private apps to learn more.

📘

The user account provided in the authorization request must be a global admin.

Authorization flow for public apps

To authenticate a public app, you need to create an app to generate a client id and secret from the Dev Dashboard. Then create a validation setup step in your app with a callback URL. When your app is installed we'll provide an install id and an access token that you can provide in an authorization request to get an access and refresh token. Learn more about authentication for public apps.

1. The user makes a request to install the app typically through the Envoy Dashboard however, this could be through a page hosted in your app.
2. The user is redirected to Envoy to load the OAuth grant screen and request the required scopes.
3. Envoy displays a prompt to receive authorization and prompts the user to login if required.
4. The user consents to the scopes and is redirected to the redirect_uri.
5. The application makes an access token request to Envoy including the client_id, client_secret, and code.
6. Envoy returns the access and refresh token to the application.
7. The application uses the token to make requests to the Envoy API.
8. The Envoy API returns the requested data.