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 - Code grant flow example
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: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.