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 - Authorization 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: developers need to perform this step within the MailUp Dev portal* in order to receive the 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 the client credentials should be saved in a safe way (e.g. inside the application code) in order to prevent any changes. The developer is in charge of keeping them secret and safe.
- Authorization: the client application requests the user an authorization by sending its private credentials to the authorization server. The authorization server authenticates the client application and redirects the user to a private page. If the login is successful, the user is asked to confirm the authorization to the application. After the confirmation, the server will provide an authorization code to the client application.This authorization code has limited duration: it should not be saved and should be immediately used to request an access code via an authorization server.
- Impersonation: the client application requests an access token by sending client credentials and authorization code to the authorization server. If the provided data are valid, the server returns the access credentials (access_token, refresh_token and expiration timespan) to be used for resource requests. Access credentials should be stored for future use.
As the token has limited duration, 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 the MailUp Dev portal is not accessible.