This is the necessary flow to be implemented by any client application who wants to use MailUp API. By using this flow, the client application exchange its own credentials with MailUp authorization server, requesting for user authorization to access his MailUp data. If the user confirms the authorization, the client will receive the tokens necessary to impersonate the user and access its MailUp resources.
This kind of flow, not only lets the client application impersonate the user, but grants the user that his private credentials are only handled by MailUp, nor username or password could be intercepted and stored by the client.
Figura 1: OAuth v2: 3 legged - Code grant flow example
In the picture above are presented the generic operations involved in the authorization process.
Looking at the picture we can easily subdivide those operations in three main steps:
- Client application registration:this step must be done by the developer on MailUp Dev portal* and it is necessary to receive the application credential (client_id and client_secret). Without those credential the application will never be recognized by the authorization server and no access will ever be granted to it. The client credentials must be saved inside the application code or in a convenient manner so nor the user nor any other could change them. Is a developer responsibility to keep them secret and not to exchange them with anyone.
- Authorization:In this step the client application request for user authorization by sending its private credentials to authorization server. The authorization server will authenticate the client application and redirect the user to a private page. After a successful login, the user will be asked to confirm authorization to the application. If confirm is given, the server will provide the client application with an authorization code.This authorization code has limited validity in time, must not be saved and must be immediately used to request authorization server for an access code.
- Impersonation:In this step the client application will request for an access token by sending to the authorization server its client credentials and the authorization code. If provided data is valid, the server will return the access credential (access_token, refresh_token and expiration timespan) to be used for resource requests.The access credential should be saved for further use.
Because access token has limited validity, it should be refreshed from time to time. This is possible by requesting 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 to refresh the access token so it's up to the developer how to proceed.
Basically the application should check for access token expiration time or intercept http status codes and handle them in a convenient manner.
*Please contact MailUp support if MailUp Dev portal is not accessible.