Help Desk Software

Set up Gmail OAuth authentication for use with Hesk

This guide works with Hesk version 3.4.0 and newer. To use OAuth, please upgrade to the latest version of Hesk.

Setting up OAuth authentication requires a bit of work and configuration; please be patient.

Unless you are a Google Workspaces user or plan to verify (Publish) your help desk application on Google, note that OAuth refresh tokens will expire every 7 days in Google. In this case, you may want to set up an App Password instead and use Basic authentication.


What you will need:

  • a Hesk administrator account,
  • a Google account,
  • your Google mail (Gmail) account must have IMAP enabled to allow fetching emails,
  • cURL support enabled in your PHP (check with your hosting company)


Part 1: prepare Hesk

  1. login into your Hesk admin panel with an administrator account
  2. go to Hesk > Admin > Tools > OAuth Providers
  3. click the New Provider button
  4. give the provider a descriptive name, for example, "Google"
  5. into the Authorization Endpoint URL field, enter:

  6. into the Token Endpoint URL field, enter:
  7. keep the form open and continue with the registration steps below in a new browser tab or window

    New OAuth provider

Part 2: register Hesk

  1. Open the Google API Console.
  2. on the Enabled APIs & services page, click the CREATE PROJECT link

    New project
  3. give the application a name, for example, Hesk OAuth or Help desk or something that will help you recognize it, then click the CREATE button.

    Create a new project
  4. when the project is created, click the + ENABLE APIS AND SERVICES link

    Enable APIs and services
  5. in the search box, search for Gmail api

    Search for Gmail API
  6. select the Gmail API from the list and click the ENABLE button

    API search results
    Search for Gmail API
  7. open the OAuth consent screen, select desired user type, and click CREATE

    OAuth consent screen
  8. enter your help desk details (App Name, User support email, Developer email) and click SAVE AND CONTINUE
  9. on the next Scopes sub-page, click ADD OR REMOVE SCOPES
  10. in the filters box, type in Gmail API and select it - the one with the scope set to  
    Gmail scope
  11. click the UPDATE button at the bottom to add the Gmail API scope
  12. at the bottom of the app registration page, click SAVE AND CONTINUE

    Restricted scopes
  13. on the Test users page, click + ADD USERS, then select the email account you will use with Hesk and add it.

    When all the users you need are added (likey just the one you will use to send/fetch emails in Hesk, or maybe another test one), click SAVE AND CONTINUE

    Test users
  14. now open the Credentials page and click + CREATE CREDENTIALS, and select OAuth Client ID

  15. under Application type select Web application, and give it a name

    App Type
  16. under Authorized redirect URIs click ADD URI and enter your enter the full URL address of your Hesk oauth_providers.php file, for example:

    Remember, this file resides inside the Hesk's /admin directory, so if you renamed the admin directory, make sure to set the correct Redirect URI!

    It is very important to enter the correct URL of your oauth_providers.php file. You can copy the URL of the Hesk OAuth Providers page from your browser address bar and paste it into the Authorized redirect URIs box at Google.

    Authorization URI
  17. click CREATE
  18. copy Your Client ID into Hesk > Tools > OAuth Providers > New Provider > Client ID field

    Application registered

  19. copy Your Client Secret and paste it into Hesk > Tools > OAuth Providers > New Provider > Client Secret field
  20. go to your Hesk > Tools > OAuth Providers > New Provider form, and into the Scope box, enter (copy from below):
  21. your New Provider form should now be full. Click Save, and you will be redirected to Google for verification.

    Filled in New OAuth provider form
  22. at Google, sign in with the account you will use in Hesk for email sending and/or fetching
  23. on the Google hasn't verified this app page, click Continue

    Google app not verified page
  24. click Continue on the permission request page to allow Hesk to access the mailbox and/or send emails using the selected account

    Google permission request page
  25. Congratulations - your new OAuth provider is now (hopefully) registered in Hesk. You can go to the Hesk > Settings > Email page and select this OAuth provider for authentication.
    OAuth provider verified





Help Desk Software