Developer Documentation

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

Authentication types

Access tokens vs OAuth2 tokens

To access the Gorgias API, you'll need an access token. This access token can be used for your own Private app (your own Gorgias account or development app) or for Public use (available to Gorgias customers). Learn more about Application Types.


Note that Access Tokens (OAuth2 or API keys) have the same permissions as the user that holds them. This means that you can do anything an Admin can do using their Access Token. If you use an Access Token for an Observer Agent for example then you can only do the things that an Observer agent can do and so on for other Gorgias Roles. Learn more about roles here.

Access Tokens (aka API Keys)

Access Tokens (aka API keys) are similar to user passwords except that they are created for applications that need access Gorgias' API and can be easily reset/revoked without changing the associated user password. Access Tokens are generated for each user and are not on the level of the account.

When should you use Access Tokens?

Read more about different Application Types and the Authentication type you can use for each. Currently Access Tokens can only be used with Private Apps.

To get your API Access Token login into your Gorgias account and navigate to Settings -> REST API

Gorgias Access TokenGorgias Access Token

Gorgias Access Token

You got your Access Token (aka API Key). What now? You can now use it with our REST API Authentication and do some API requests.

curl --request GET \
  --url https://your-customer-account.gorgias.com/api/account \
  --header 'Authorization: Basic base64encode(USERNAME:API_KEY)'

Note that since we're using HTTP Basic Authentication the USERNAME:API_KEY pair need to be base64 encoded string. Note the : between the USERNAME and API_KEY - it's a separator used to know which is the username and which is the password.

OAuth2 Bearer Token

Use OAuth2 to authenticate all your application's API requests towards your customers' Gorgias API. OAuth provides a secure way for your application to access Gorgias data without having to store and use the passwords/access tokens of Gorgias users, which is sensitive information. OAuth2 also provides more granular permissions via OAuth2 Scopes which increases security of our customers' data.

When should you use OAuth2 Access Tokens?

Read more about different Application Types and the Authentication type you can use for each. OAuth2 Bearer tokens can be used with all apps (private or public).

In OAuth2, the authentication is done using Bearer Access Tokens. Once you get them you can perform API calls like so:

curl --request GET \
  --url https://your-customer-account.gorgias.com/api/account \
  --header 'Authorization: Bearer YOUR-PLAIN-TEXT-ACCESS-TOKEN'


Access Token expiration

Please note that OAuth Bearer Access Tokens expire after some time. This is done because sometimes Applications only need temporary access to the API (Ex: one time import of data). If your app needs permanent access you should request the offline scope described in OAuth2 Scopes and get a refresh_token that can be used to get a new access_token when the old one expires.

Updated 2 months ago

What's Next

How do you get this initial Access Token in the first place? Continue the guide below:

OAuth2 apps

Authentication types

Access tokens vs OAuth2 tokens

Suggested Edits are limited on API Reference Pages

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