Overview
This is the required flow to be implemented by any client application using the MailUp API. When following this flow, the client application exchanges credentials with the MailUp authorization server, requesting user authorization to access the data in the MailUp account. If the user grants the authorization, the client will receive the tokens to impersonate the user and access the MailUp resources.
Not only does this kind of flow let the client application impersonate the user, but it also gives the user the peace of mind that his private credentials are only handled by MailUp. No username or password can be intercepted and stored by the client.
OAuth v2: 3-legged authentication - Code Authorization code grant flow example
3-legged Authentication
In the picture above you can view the generic operations involved in the authorization process, which can be divided into three main steps
...
.
Client application registration:
...
API keys
Developers that wish to use the MailUp REST API must first get a pair of API keys*
Once logged into their MailUp developer account, they can use the Developers tab to request application credentials (client_id and client_secret). Without
...
these credentials, the application will
...
not be recognized by the authorization server and
...
it won't be able to access the system. We recommend that these credentials are saved in a safe way (e.g. inside the application's non-public source code) to prevent any changes. The developer is responsible for keeping them secret and safe.
*Please contact MailUp support if the MailUp Dev portal is not accessible.
Authorization
The client application requests to be authorized to communicate with the MailUp REST API by sending its private credentials to the authorization server.
The authorization server - after successfully recognizing the application as an authorized app - will
...
Because access token has limited validityask users to authenticate themselves by taking them to a login page.
If the login is successful, the user is asked to confirm that the application should be authorized to communicate with the user's MailUp account.
After receiving user confirmation, the authorization server provides an authorization code to the client application.
This authorization code is time-limited in duration: it should not be saved and should be immediately used to request an access code via the authorization server, as indicated below.
Impersonation
The client application requests an access token by sending:
- Client credentials
- Authorization code
... to the authorization server. If the provided data are valid, the server returns the access credentials:
- access_token
- refresh_token
- expiration timespan
... to be stored and used for future API calls.
Token refresh
As the access token has a limited duration, it should be refreshed from time to time. This is possible by requesting submitting a request to the authorization server to refresh tokens providing to it the client credentials and the previously obtained refresh token. Different are the ways the client could recognize the necessity . The two parameters to be provided are:
- Client credentials
- Refresh token
There are different ways in which the client could detect the need to refresh the access token so : it's up to the developer how to proceedchoose one of them.
Basically, the application should check for periodically the access token expiration date & time, or intercept http the HTTP status codes and handle them in a convenient mannerconveniently.
...