Introduction
Envoke uses OAuth to allow users of an external application to authorize connecting to their Envoke account. Envoke uses the OAuth 2 “authorization code” workflow.
NOTE: This document focuses on the requirements for using OAuth with Envoke. For some resources with more focus on OAuth see:
Process summary
When a user requests authentication with Envoke, your application will direct them to the Envoke OAuth page, where they will login, review, and authorize your application.
They will be redirected back to your server with a “code” query parameter. Send that code in a request from your server to Envoke to receive an access token.
Keep the access token use it for all subsequent requests to the Envoke API.
Example request
Simple request to the contacts API using curl. Note the header "Authorization: Bearer" followed by your access token.
curl 'https://e1.envoke.com/v1/contacts?limit=1' -H 'Authorization: Bearer [ACCESS_TOKEN]'
Note: Envoke access tokens expire after 1 year after which the user will have to re-authorize. The user may also revoke your application’s permission at any time.
Register your application with Envoke
Before users can authorize your app with OAuth your application must be registered with Envoke. To register your application you’ll need to reach out to us. The best way is to contact support.
Have the following required details prepared:
Application name: a short, recognizable name to be presented to the user
Redirect URI: where to redirect the user (and send the authorization code) after they approve the request
Description: A brief description of the application / integration (text only)
Homepage URL
Icon: a 72 x 72 (or larger) icon image
Once approved, we’ll respond with your client ID and client secret. Use your client ID and secret along with the following OAuth configuration details.
Grant type: authorization code
Authorize URI: https://e1.envoke.com/ext/oauth/authorize
Postback URI: https://e1.envoke.com/ext/oauth/access_token
Scope: "all"
Client authentication method: request body
Implement OAuth on your server
To begin, redirect your user to the URL:
https://e1.envoke.com/ext/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
After the user approves your application, they’ll be redirected back to your application with a query string parameter named "code". Use this to request your access token via a POST request to:
https://e1.envoke.com/ext/oauth/access_token
Example using RESTer
RESTer is a tool for perform HTTP requests and allows for testing requests with authorization headers with Basic, OAuth 2 or Cookie authentication.
It can be a convenient way to test your OAuth setup with Envoke. Below is a screenshot showing the configuration for an OAuth 2 workflow request:
