Developer Documentation

Guides and technical documentation to help you start building integrations on Gorgias

OAuth2 apps

A guide on how to create and publish your OAuth2 App into our Partner Portal.

Gorgias provides OAuth2 authentication protocol so that you can securely request and access your customers' Gorgias data. This is a guide on how to set up OAuth2 for your app.


When do you need to use OAuth2?

You'll need to setup an OAuth2 app if you are building an integration with Gorgias that accesses other Gorgias' customers data. Read more about different Application Types.

1. Create an App

Register your app on our partner portal here - follow the registration steps there and submit your app.

You will need an App URL. For example: https://your-app.com/gorgias/oauth/install (Gorgias will redirect the users on this URL when they click the Install button in the Gorgias App Store.

Additionally you will need to setup the Redirect URLs so the Gorgias OAuth2 provider knows where to redirect the user when the authorization step finished. For example you can use a value like: https://your-app.com/gorgias/oauth/callback

2. Client IDs and Secrets

Once you submitted your draft app you will need to get your Client ID and Client Secret. An example:

Gorgias OAuth2 Client ID and Secret example.Gorgias OAuth2 Client ID and Secret example.

Gorgias OAuth2 Client ID and Secret example.

These credentials are necessary to identify your app when a Gorgias User "installs" your app and authorizes the requests to get the access_token from Gorgias. Save them somewhere securely in your config/environment files.

3. OAuth2 authorization flow

Now that you have your Client ID and Secret please refer to the authorization flow below for a high-level view of the different steps of obtaining the Access Token needed to make OAuth2 bearer token requests.

Gorgias OAuth2 authorization flowGorgias OAuth2 authorization flow

Gorgias OAuth2 authorization flow

Let's dissect the above diagram into steps:

"Install" button pressed

When a Gorgias user accesses the app listing, they can click on the "Install" button in the Helpdesk App Store. At the moment, the temporary App Store set-up with the OAuth2.0 flow is available under the URL https://ACCOUNT_SUBDOMAIN.gorgias.com/app/apps.

Gorgias Helpdesk Temporary App StoreGorgias Helpdesk Temporary App Store

Gorgias Helpdesk Temporary App Store

Note that the above install button will only be visible for Gorgias users if your app passed our App approval process described in the Publishing an app] doc. To "preview" your App while developing we created a handy "Preview" button so you can test out your app before submitting for review:

Preview button in the Partner portal.Preview button in the Partner portal.

Preview button in the Partner portal.

Once the Gorgias user clicks the "Install" button they will get redirected to the App URL that was setup in the App creation step:

App URLsApp URLs

App URLs

The redirect then takes the form of the following URL: https://your-gorgias-app.com/oauth/install?account=acme - where acme is the gorgias subdomain that the request came from - this way your app will know which Gorgias customer the requests is coming from. To simplify our examples, let's use acme as the Gorgias account that you'll work with.


Gorgias Subdomains

Note that all requests towards our APIs need to go to a specific Gorgias account (identified by the subdomain). Ex: GET https://acme.gorgias.com/api/account

Once you receive a request from that URL your app should generate an authorization redirect towards https://acme.gorgias.com/oauth/authorize with the necessary URL params (see more about this below).


OAuth2 Client SDK

We highly recommend using an official OAuth client library to handle the entire OAuth2 authentication flow - this is especially useful when dealing with expiring tokens. There are lots of great SDKs in many different languages. Find out more here.

An example redirect authorization redirect can look like this:

curl 'https://acme.gorgias.com/oauth/authorize?\

In a real-world scenario the above request will come from the user's web browser and will contain cookies, but they are omitted here for brevity.

/ouath/authorize URL Parameters and what they mean

  • client_id: The Client ID that you had got from the developer portal.
  • scope: "permissions" the app requires for completing the authorization flow. More about this in OAuth2 Scopes.
  • redirect_uri: Where to redirect (on the app's back-end) after the app is authorized in order to get the tokens. Make sure to have this URL among your Redirect URLs configured in the Portal.
  • state: Random string, protecting against CSRF attacks.
  • nonce: Random string, binds it with the token, so we identify the original request that issued it.

Consent page

A permissions consent page will be displayed and if the customer accepts them they will be redirected into the redirect_uri with a code parameter and the very same state you provided. Through state you can verify if the request was originally triggered by you.

Example consent window:

Gorgias Auth Consent windowGorgias Auth Consent window

Gorgias Auth Consent window

Getting the access_token

To receive the access_token you need to make a POST call into Gorgias' /oauth/token endpoint (Ex: https://acme.gorgias.com/oauth/token` with the code received during the authorization step. During this step you need to authenticate the request with the app credentials.

curl -u <client_id>:<client_secret> -X POST https://acme.gorgias.com/oauth/token \
  -d grant_type=authorization_code \
  -d redirect_uri="https://your-gorgias-app.com/oauth/callback?account=acme" \
  -d code=ruu5ebEeAcdxSYrbR7T65xpFhA6fo99O98xX9wlRhqnFehj6

App credentials are simply:

  • client_id: Generated in the Developer Portal.
  • client_secret: Generated in the Developer Portal.

/oauth/token URL Parameters

  • redirect_uri: The very same redirect URL you used during the authorization step.
  • code: The code you received after successfully authorizing the app.

You'll get a JSON response containing the access_token and refresh_token.

    "scope":"openid email profile offline write:all",
  • access_token can be used with the Authorization: Bearer <token> header in order to make authorized Gorgias API requests.
  • refresh_token will be used for issuing new access tokens once the one you use expires.

You can now use the access_token to make requests against the Gorgias API. For example:

curl --request GET \
  --url https://acme.gorgias.com/api/account \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6'

Wohoo! Congrats! Now you have access to Gorgias API using OAuth2. If your app requires a "permanent" authorization you should read below on refresh tokens.

Issuing a new access token

The received access_token is valid for a period of time, afterwards you need to issue a new one using the non-expiring refresh_token. Example:

curl -i -u <client_id>:<client_secret> -X POST https://acme.gorgias.com/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=Bn8nh9P76uDYZb6wADnV93CyuiqaKaaI00mXQpWFWjfbBR06

You should receive a response like:

    "scope":"openid email profile offline write:all",

Revoking the refresh token (uninstalling the app)

A Gorgias user can remove access of the app by pressing the Uninstall button or by manually revoking the refresh_token. Note that the app will still have access until the current access_token expires as it is stateless.

You can also do it for the user like so:

curl -i -u <client_id>:<client_secret> -X POST https://acme.gorgias.com/oauth/revoke \
  -d token=<refresh_token>

To obtain a new refresh_token the Gorgias user has to go through the app authorization process again.

Closing notes

  • OAuth2 enhanced security: PKCE layer isn't enabled yet (code_challenge, code_verifier)
  • Sample Flask Application that uses the entire OAuth2 flow can be found here

Updated about a month ago

OAuth2 apps

A guide on how to create and publish your OAuth2 App into our Partner Portal.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.