Authentication

Before you can start building with the Mailabl API, you need to provide valid authentication through an access token. There are 2 possible methods how to get an access token and thus authenticate your requests: access tokens created within the application and password grant.

Authenticating with access tokens created within the application​

This method (which can also be called as API keys) is a standard approach when communicating with APIs. Especially when the communication is made purely on a machine-to-machine (M2M) basis, without a user interface and without a need for the user to interact with the system to do any authentication. Meaning you authorize a service rather than a specific user.

These tokens don't expire, until you manually revoke them.

Getting the access token​

This action can be done within the application under Settings > Integrations > API Integration.

We strongly suggest you name your token so that its use case can be easily and understandably distinguished from others.

Revoking the access token​

Revoking an access token is always a good idea to do when the integration has become obsolete. Or must be done when your application has become compromised.

The action can be done within the application under Settings > Integrations > API Integration.

Authenticating with a password grant​

Password grant should be used when your (highly trusted!) application has to act as a specific user. For instance when you're creating an app where a Mailabl user has to log in with their username and password. After a successful login your application is given a short-lived access token (also known as PAT - personal access token) with what you can make your requests against Mailabl API. All requests are then authorized against an actual user with predefined scopes and permissions. Also all entries and actions are created as that specific user.

Getting the access token​

To get the access token you first have to login via the API:

mutation {
  login(input: { username: "email@email.com", password: "12345" }) {
    accessToken
    refreshToken
    expiresIn
  }
}

Which will give you the following response:

{
  "data": {
    "login": {
      "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...",
      "refreshToken": "def502004531ba2a1745464642...",
      "expiresIn": 259200
    }
  }
}

With the given accessToken you can now start making requests towards Mailabl API by including the token in the HTTP headers:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

Refreshing the access token​

As we saw in the previous section there were 2 additional fields requested with the access token: refreshToken and expiresIn. This means that the access token is usable for only a fixed duration, which is extremely useful for security concerns.

The given accessToken can only be used for the given number of seconds after making the login request (3 days, 259200 seconds). After the given number of seconds have passed you'll need to make a request to refresh the access token:

mutation {
  refreshToken(input: { refreshToken: "def502004531ba2a1745464642..." }) {
    accessToken
    refreshToken
    expiresIn
  }
}

This will give you a new access token, which is valid for another 3 days.

Permissions​

We strongly believe that no access token should be allowed to do everything within the system - at least not by default.

That's why we also urge you to follow the principle of least privilege in according to which a user or access token should have only the minimum access privileges to perform a specific task or job and nothing more.

For this we've implemented permissions which can be applied to both users and access tokens created within the application. This allows account administrators to specify exactly what privileges each of them has. Whether they can only access a handful of modules and actions or indeed access the whole system, should it be necessary.

This approach is crucial where you have multiple systems integrated with Mailabl which should't have access to the whole system: ticketing system, website forms etc.

Rather we suggest you create multiple access tokens for different jobs.

Liability​

It is your responsibility to keep the tokens in a safe manner.