Gmelius API documentation

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Gmelius API Overview

Welcome to the Gmelius API!

Gmelius offers a new way to collaborate, manage projects, and automate your workflows. The Gmelius API lets you easily create a functional application or integration around its two core resources for team collaboration: shared email conversations and kanban boards. Gmelius sequences are also available through our API.

Not a developer? Checkout our API presentation to learn what you can do with Gmelius thanks to a few common use cases.

How do I register?

Sign up for Gmelius!

Once logged in to our dashboard, head to your account page to get your API credentials.

Note 1: Access is for now restricted to our Growth and Enterprise plans. API credentials appear for admin and managers only. If you’d like to give our API a spin and see what it can or cannot do, contact our Success Team to request a trial: success@gmelius.com.

Note 2: Your API credentials solely allow access to the resources of your subscription.

API format

The Gmelius API is organized around REST and resource-oriented URLs. Our API uses standard HTTP response codes and methods.

API endpoints return JSON-encoded responses and accept JSON-encoded request bodies.

Except for authentication where the implemented framework OAuth 2.0 / OIDC deals with form-encoded request bodies.

Getting started

To get started with the Gmelius API, see the fully working code sample.

This small application performs OAuth 2.0 authentication and then displays a Gmelius board.

Authentication

Authentication is the process of verifying the identity of a user. In our case, it means a way to allow your third-party application to access Gmelius resources acting as a user logged in Gmelius.

Here is how it works. The process transforms your application credentials and a logged-in user into an access token and a refresh token. These tokens help you access the Gmelius API. The access token is used in the authentication header as a Bearer, the refresh token helps you create some new access tokens.

All the process of authentication is done with the protocol OAuth 2.0 and a layer on top of it called OpenID Connect 1.0. We will not go into details in these frameworks but we will outline some aspects below.

Let's say that OAuth 2.0 introduces an intermediary step of obtaining an authorization code. It is hence referred to as the authorization code flow. We clarify the parameters and the intermediary steps below.

Please note here that OAuth 2.0 also introduces a mechanism, called scope, to limit an application's access to specific resources.

We divide this section into five parts.

1. We describe the authorization code flow.
2. We explain how to refresh an access token that has a limited lifetime of one hour.
3. We detail scopes.
4. We reference some API endpoints related to authentication.
5. Finally, we give an example of an authentication process. If you are familiar with OAuth 2.0, this might be sufficient to get started.

Authorization code flow

We describe here the process of obtaining an access token and a refresh token from application credentials and a logged in user.

An intermediary step is included to obtain a so-called authorization code according to the following schema. This intermediary step is here for security reasons.

Get authorization code

The parameters are the following :

• client_id is part of your credentials,
• redirect_uri is the address where the authorization server will redirect to, giving the authorization_code as query parameter
• scope is actually a list of scopes. Scopes restrict read-write access to specific resources (more on that in the next section). The list is separated by semi-colons. A specific scope offline_access is asked in both steps
• code_challenge is the challenge string of PKCE (see below)
• logged in Gmelius user on behalf of whom the application asks access.

Include these parameters in the URL

https://app.gmelius.com/oauth/authorize?client_id=&redirect_uri=&code_challenge=&scope=

Redirect your user to this URL. Once the user is logged in, this will display the Gmelius consent screen where authorizes your application to access Gmelius resources on their behalf.

Once the user accepts, this will redirect to the redirect URI with the authorization code as a query parameter.

Get access token and refresh token

You are now able to exchange this authorization code for an access token and a refresh token.

In this request, both your application credentials client_id and client_secret are used for basic authentication. More precisely a request header field in the form of Authorization: Basic {client-header}, where client-header is the Base64 encoding of client_id and client_secret joined by a single colon :.

The code_verifier of PKCE also comes into place, see below.

For client-header=btoa(client_id+':'+client_secret)

The HTTP response includes

• access_token is the bearer used in HTTP calls to Gmelius resources. It has a limited lifetime of one hour.
• refresh_token is used to produce a new access token with the same grant once the access token is expired. Note that refresh tokens also expire - after two months - and are renewed, see below.

PKCE

PKCE refers to Proof Key for Code Exchange. This technique allows to mitigate the threat of having the authorization code intercepted. It involves the client first creating a random secret code_verifier, and then using that secret again when exchanging the authorization code for an access token. This way if the code is intercepted, it will not be useful since the token request relies on the initial secret.

The value first sent when asking for an authorization code is not the code verifier but a hash of it code_challenge. The hashing method is S256: code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier.

code_challenge = base64url(createHash('sha256').update(code_verifier).digest())

Refreshing tokens

Refreshing access tokens

Access tokens have a limited lifetime of one hour for security reasons. In order to renew them, OAuth 2 gives a specific method described below.

Note that the renewal occurs with the same grant. This means the successive access tokens have the same rights, in particular the same scopes as when the user first clicked to authorize your third party application.

Access tokens are renewed with a specific token given at the end of the authorization code flow called a refresh token.

For client-header=btoa(client_id+':'+client_secret)

Refreshing refresh tokens

A refresh token has a much longer lifetime of 60 days but also expires too. Upon first usage after half its lifetime, aka 30 days, the previous response will give a new refresh token. Be sure not to miss this singular response containing a new refresh token even if the first refresh token remains valid until the end of its lifetime.

Scopes

Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.

Note that any scope asked for a user access token has to be allowed at the application level. Application level scopes are allowed in the Gmelius API configuration page.

List of Gmelius scopes

The list of Gmelius scopes is as follows:

Offline access

An extra scope is present in the OAuth 2.0 process: the value offline_access.

It allows an access token to be obtained from a refresh token without user interaction.

It is also asked in both steps of the authorization code flow, see here.

Scope - API endpoint correspondence

We saw previously that any access token is tied with one or more scopes. And each scope allows access to a specific set of API endpoints. We make this correspondence clear in each of the Gmelius API endpoints documented below.

Other operations linked to authentication

Introspection

For client-header=btoa(client_id+':'+client_secret)

Revocation

For client-header=btoa(client_id+':'+client_secret)

User info

Quick example

This part gives a quick example and skips any explanations about parameters and steps. Read the previous part for explanations.

• We use https://example.com as redirect_uri.
• Moreover, we ask for just one scope https://api.gmelius.com/public/auth/boards/read. That is on top of the special scope offline_access, see below.
• PKCE values code_verifier and code_challenge are as follows

code_verifier=testtesttesttesttesttesttesttesttesttesttesttest

which gives

code_challenge=lO_AJ2ilEcR6LRlckw86DAURi7qEDpnqarCj-C381Fw

Get authorization code

First, go to Gmelius consent screen:

GET https://app.gmelius.com/oauth/authorize?client_id={client_id}&redirect_uri=https://example.com&code_challenge=lO_AJ2ilEcR6LRlckw86DAURi7qEDpnqarCj-C381Fw&scope=offline_access;https://api.gmelius.com/public/auth/boards/read

This will give an authorization code in a URL :

https://example.com?code={code}

Get access token and refresh token

Next step is using this authorization code to obtain an access token and a refresh token. Use the HTTP call on the right :

For client-header=btoa(client_id+':'+client_secret)

curl --location --request POST 'https://api.gmelius.com/public/v2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {client-header}' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={code}' \
--data-urlencode 'scope=offline_access' \
--data-urlencode 'code_verifier=testtesttesttesttesttesttesttesttesttesttesttest' \
--data-urlencode 'redirect_uri=https://example.com'

This will give the following response containing your access token and refresh token.

{
    "access_token": "KxUk6Owx2Fhw221nmiWnm7fm9kH6V7a8NxlRTfttYes",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNscmU5NXBnYVFoeTZtNVBiSU8ybDUwV2s4T2FKYUg1NjJsNzZxZGlXdUkifQ.eyJzdWIiOiIwYTI1Yjg1NGFmZjhhYTZiNzFjOTBkMGRmMjFkNmUzOCIsImF0X2hhc2giOiI3RmhtU1h1ekUzWGk0X3VBYktWajNRIiwiYXVkIjoiYmZlYjkxN2E4ZDFkMjY3NjZhYmE5Mzc5YWVjYzk2MTQtNjlFcHg3WTJUZFF6YkpCdzE1b2hSLmdtZWxpdXMuY29tIiwiZXhwIjoxNjA0MDU1Njg0LCJpYXQiOjE2MDQwNTIwODQsImlzcyI6Imh0dHBzOi8vYXBpLmdtZWxpdXMuY29tL3B1YmxpYy92MSJ9.PbGZm354CBuXiRKeVUdblhEphhfZFNIl1fodzIil4ASFtp_6wsgcKaU-QdjsE94X40eudnaigMS-6BIc3CxnxJ3AVNhyYb0F9uqkVfNp6oRsrkxMMywdsCbxeSe_XfWMrDl4t2zzIB5nDjzJBsqje8JqtzDcj4Mxi-MXNgMbbVayZezkAw2Uvyfl8inL5y-eX-Ym92sICKtpZ9Qm2kNqh6gRlY4hJdkqyj_I1pcJkoxTDpXPsfurDh3mStPdOicHwtiU0FtRI_2DzOeAm4RJXirzm6rX-qzs4bWwMCvmtQOBOifnQjxRPe4D4-XIWsHPXpb-RcHUujVF50p8sHf-RA",
    "refresh_token": "PEPvFWZHUuJzyDJEUb8PUk3F02975ymiyxHxjpVy_p1",
    "scope": "openid offline_access https://api.gmelius.com/public/auth/boards/modify",
    "token_type": "Bearer"
}

Access protected resources

Using this access token as a bearer, you are now able to access Gmelius resources. More precisely, resources that just require reading boards and related metadata because the scope is https://api.gmelius.com/public/auth/boards/read.

For example, for listing boards, see here.

Schemas

Be careful on deserialization on these objects because they might contain additional properties in future versions of Gmelius API. You may ignore unkown properties, e.g. in Java with the annotation

@JsonIgnoreProperties(ignoreUnknown = true)

Misc

Rate limits

To protect our servers, the Gmelius API imposes rate limits per user. We throttle requests to our API using the token bucket algorithm. For simplicity, let's say the soft-limit is 1 request per second with the same user access token. But you can sparsely send up to 100 requests at the same time.

Please note that if your application creates multiple access tokens per user, the rate limit will be shared across these tokens.

Rate limit error

When a rate limit has been exceeded, Gmelius will return a response with a status code of 429 and the error message Too Many Requests.

Details on rate limit

For applying rate limits, the Gmelius API implements the token bucket algorithm. Such an algorithm is defined by two values:

• capacity: number of requests at the same time
• refill-rate: rate at which new allowed requests are added per second

In fact, the Gmelius API overlays two separate token bucket algorithms with the following parameters:

Without going into details into the algorithm, here are a few examples to help you understand these parameters:

If a caller submits requests at the rate of one per second, Gmelius processes all requests without dropping any.

If the caller sends 200 requests at once, Gmelius serves 100 of those requests and rejects the additional requests with 429 Too Many Requests error responses.

If the caller submits 100 requests at once and then evenly spreads another 100 requests through the remaining 100 seconds, Gmelius processes all 200 requests without returning 429 Too Many Requests error responses.

Special rate limit for sequences

In order to comply with Gmail limits, the endpoint for enrolling a user in a sequence has a special rate limit: an additional token-bucket with (capacity, refill rate) of (224, 1/360) if you have a @gmail.com account or (1224, 1/360) if you have a Google Workspace account is applied.

Errors

Gmelius uses the following standard error codes