Get a token for private apps

❗️

This guide only applies to private apps that you plan to use only for your company. If you are building an app for other Envoy customers please refer to this guide for retrieving an access token.

Create an API user

Before you can make a call to the API, you need to set up an API user account. For demonstration purposes, this guide will show you how to authenticate with the Envoy API using the OAuth2 password grant type.

1. Create an employee manually in your [employee directory] (https://dashboard.envoy.com/employees).
2. Assign the user a Global Admin role.
3. Make sure the setting Show employee as a host on the Visitors Kiosk is disabled

Get client credentials and secret

You'll need a client id and secret to retrieve an access token to authenticate with the API. To generate a client id and secret you will need to create an integration using the Dev Dashboard.

1. Visit the Dev Dashboard
2. Click Create New.
3. Provide a name for your integration
4. Under API Scopes add the scope locations.read
5. Check Is the integration ready to be displayed?
6. Click Save Integration

Get a Client API Key

For developers that prefer a simplified authentication flow that does not require periodic calls to refresh the token, we provide a Client API Key as a long-lived token that can simply be passed in via the request X-API-Key header on any request to https://api.envoy.com/v1.

If you pass the https://api.envoy.com/v1/ request via the X-API-Key header it will work without additional complexity. Note this functionality ONLY works with the newer https://api.envoy.com/v1/ APIs and will not work with our legacy https://api.envoy.com/v3/ APIs.

curl --location --request GET 'https://api.envoy.com/v1/locations'
	--header 'Content-Type: application/json' 
	--header 'X-Api-Key: {YOUR_CLIENT_API_KEY}' 

Get an access token

You'll need to exchange the client id, secret, and username and password to get an access token that can be used to make an API request.

Call the token API /oauth2/token and format your request using the curl example below.

📘

Tokens expire after 24 hours. You can use your refresh token to request a new access token when the old one expires.

curl --location --request POST 'https://api.envoy.com/oauth2/token' \
--header "Authorization: Basic $( echo -n {ENVOY_CLIENT_ID}:{ENVOY_CLIENT_SECRET} | base64 )" \
--form "username={USER_EMAIL}" \
--form "password={PASSWORD}" \
--form "scope=token.refresh,locations.read" \
--form "grant_type=password"

{
    "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"
}

Exchange your refresh token for a new access token

curl --location --request POST 'https://api.envoy.com/oauth2/token' \
--form "client_id={ENVOY_CLIENT_ID}" \
--form "client_secret={ENVOY_CLIENT_SECRET}" \
--form "refresh_token={REFRESH_TOKEN}" \
--form "grant_type=refresh_token"

{
    "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"
}