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:

https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow

https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type

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.

Chrome plugin | Firefox plugin

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:

Did this answer your question?