An unlisted app is not installed from the Envoy Dashboard but is instead installed from outside of the Envoy Dashboard, e.g., your web application's settings page.

When the user installs the app, they will be redirected to Envoy's OAuth prompt to authorize your app. After authorizing your app, the user will be redirected to your preconfigured redirect URL with an authorization code that can be exchanged for an access token. You can then use the access token to make API requests to Envoy.

Enable external OAuth installs

Visit the Dev Dashboard
Find the unlisted app you want to set up OAuth for and select Configure.
Check Externally using OAuth2.

Add a redirect URL. This is the URL that we will redirect to with the authorization code after the OAuth flow has completed.
Select Save Integration.

Ask for the user's permission

To get an authorization code, you will need the user to authorize your app by redirecting them to Envoy.

Include the client id, OAuth scopes, and the redirect URL configured in the previous step.

Redirect to Envoy's OAuth prompt

https://app.envoy.com/a/auth/v0/authorize?response_type=code&client_id={YOUR_CLIENT_ID}&redirect_uri={YOUR_REDIRECT_URL}&scope=locations.read+token.refresh

❗️
In the above example, the scopes are space-separated but have been URL-encoded, resulting in the + signs. Do not double-encode the + signs.

Get an access token

Once the user authorizes your app, we will redirect to {REDIRECT_URL} with a code query param. Exchange the code string for an access token and refresh token.

Call the token API using the curl example below.

https://app.envoy.com/a/auth/v0/token

curl --location --request POST 'https://app.envoy.com/a/auth/v0/token' \
--header 'Content-Type: application/json' \
--data-raw '{
   "grant_type": "authorization_code",
   "code": "YOUR_AUTHORIZATION_CODE",
   "client_id": "YOUR_CLIENT_ID",
   "client_secret": "YOUR_SECRET"
}'

{
    "token_type": "Bearer",
    "access_token": "YOUR_ACCESS_TOKEN",
    "expires_in": 86400,
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "refresh_token_expires_in": 2592000,
    "state": null,
    "company_id": "10000"
}

Refresh an expired access token

When the access token expires, use the refresh token to receive a new access token. To get a new access token if expired call the token API using the curl example below.

https://app.envoy.com/a/auth/v0/token

curl --location --request POST 'https://app.envoy.com/a/auth/v0/token' \
--header 'Content-Type: application/json' \
--data-raw '{
   "grant_type": "refresh_token",
   "refresh_token": "{REFRESH_TOKEN}",
   "client_id": "YOUR_CLIENT_ID",
   "client_secret": "YOUR_SECRET"
}'