OAuth from an external app
Allow users to install your app outside of Envoy using external OAuth2.
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"
}'
Updated 12 months ago