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.
  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 Integration Builder.

  1. Go to the Dashboard and click Integrations > Integration Builder.
  2. Click Connect Account.
  3. Click Create New.
  4. Provide a name for your integration
  5. Under API Scopes add the scope locations.read
  6. Check Is the integration ready to be displayed?
  7. Click Save Integration

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

Did this page help you?