Introduction

Token Generation via OAuth

Suggest Edits

Introduction

OAuth should be used by application developers who wish to build an integration to be used across multiple companies in Dialpad. If you are an admin who is using the API for your own company only, you generally do not need to use OAuth, and may create an API key instead.

OAuth gives a third party developer the ability to get a Dialpad token (API Key) on behalf of a Dialpad user. Generally you will create a Login with Dialpad button on your site. After the user clicks the button and consents, you would be able to get an API key on behalf of the user.

  • When the user clicks the Login with Dialpad button, the following occurs:
    • The user is sent to dialpad.com/oauth2/authorize?client_id=XXXX&redirect_uri=XXXX
    • If the user is not logged in to Dialpad, they will be prompted to login
    • After logging in, the user will be presented with a consent screen
    • After consenting, Dialpad redirects the user to the redirect_uri (your site) and provides an auth code
  • You use the auth code to acquire a Dialpad API key using a POST request against dialpad.com/oauth2/token

Setup

In order to use OAuth you must first register an OAuth application with Dialpad. To register your application, please reach out to [email protected]. You will be asked to provide redirect URI(s) for the callback part of the OAuth flow and any scopes you would like to use.

After registering, you will be provided with a client id and client secret. These will be required to initiate the OAuth flow.

Supported scopes

recordings_export: Allows publishing of recording URLs in call events.
message_content_export: Allows export of SMS content.
screen_pop: Allows the use of the screen pop API.

Getting the API key

As a third party developer your service must implement an OAuth redirect and callback.

OAuth redirect (login with Dialpad)

The OAuth redirect initiates the OAuth flow by redirecting to Dialpad. This usually happens when the user clicks a link or button to login with Dialpad on your site.

Dialpad URL to route to perform authentication:

  • Sandbox: https://sandbox.dialpad.com/oauth2/authorize
  • Production: https://dialpad.com/oauth2/authorize

URL parameters

  • (required) client_id: Provided by Dialpad
  • (required) redirect_uri: URI for the OAuth callback on the third party website (see OAuth Callback section below)
  • (optional) scope: Additional scopes to request (space separated). Scopes must be approved by Dialpad. Please reach out to [email protected] if you don't already have them approved.

OAuth callback

The OAuth callback is an API on the third party site that is the destination for the OAuth flow. This callback corresponds to the redirect_uri above.

When Dialpad redirects to this callback, Dialpad will provide a number of standard OAuth params:

  • code: Temporary authorization code used to get an API key. Valid for 1 minute.
  • client_id: Client id provided by Dialpad
  • state: Passthrough OAuth state (recommended to prevent CSRF attacks)
  • redirect_uri: Passthrough redirect URI
  • response_type: Unused (passthrough)
  • scope: Additional scopes

Next you need to make a POST request to convert the temporary authorization code into a Dialpad API key:

POST body (x-www-form-urlencoded):

  • (required) code: Temporary authorization code used to get an API key. Valid for 1 minute.
  • (required) client_id: Client id provided by Dialpad
  • (required) client_secret: Client secret provided by Dialpad

Response

{
  “access_token”: “<DIALPAD API KEY>”
}

This API key can then be used as a bearer token to call the Dialpad API.

In order to get the authenticated user information, you may use the get user API with “me” as the user id.

GET /api/v2/users/me

Deauthorization

Your application should provide a way for users to disconnect from your service. If that occurs, your application should revoke the user's oauth tokens.

If your application makes use of any event subscription features, it is also advisable to clean out any subscriptions that will no longer be needed, either by deleting them, or disabling them prior to revoking the user's tokens.

The POST deauthorize endpoint should be called with the relevant bearer token authorization header an empty request body, which will revoke all API tokens that were vended to your app on behalf of the associated user.

Updated over 3 years ago