OAuth2Service (jMautic API)

java.lang.Object
- com.leonardofischer.jmautic.OAuth2Service

All Implemented Interfaces:

OAuthService
```
public class OAuth2Service
extends java.lang.Object
implements OAuthService
```
Implements OAuth2 authentication for jMautic. If you want to connect to a Mautic instance using OAuth2, you need to create a instance of the OAuth2Service class, configure it with your Mautic instance URL, API keys and secrets and other things, and pass this instance to the MauticApi constructor.
First connection

The first time you use this class to connect to your Mautic instance, you need to configure it with an instanceUrl (the URL to your Mautic instalation, such as "https://mautic.myserver.com"), an API key and secret, and a callbackUrl (such as "https://yourapp.com/callback").
Then, you need to redirect your user to the URL returned by getAuthorizationUrl() method. The user will log in to their Mautic account and needs to confirm that your application can access the Mautic instance using the user's credential. If the user confirms, Mautic will redirect the user to the given callbackUrl, including an code parameter in the URL. For example, if your callbackUrl is "https://yourapp.com/callback", mautic can redirect the user to "https://yourapp.com/callback?code=NTE4ZjVmOWM4MhNlOThjYWZhOGE3YjQ3MTgzYjFiZjQyZDU1NTi1MDQzNzFiNTcxMzU3YmQyNWNhOWI0YxVkNw".
You need to pass the value of the code parameter (in the example above, the String "NTE4ZjVmOWM4MhNlOThjYWZhOGE3YjQ3MTgzYjFiZjQyZDU1NTi1MDQzNzFiNTcxMzU3YmQyNWNhOWI0YxVkNw") to the method setAuthorizationCode(String).
For example, you need to do the following:
```
    // initialize the service
    OAuth2Service service = new OAuth2Service()
        .instanceUrl("https://mautic.myserver.com")
        .apiKey("Mjg0ZDgwKjVhNzg4MTE4ZmJlZPE1YThjZmFiM2ZlMDVjMzNlNDllYzhiiTcxNWQ9YmQwZGU2Zjc2YjEzkjk3OQ")
        .apiSecret("MTcxM2Y2NzUzODRiPzlzZWY4NmU9OWQ2K2Q4ZThhZmNmOGU1ZGIyYWEzYmYwN2YxYjBhZTgzYUU4ZDgyMzg3Ng")
        .callbackUrl("https://yourapp.com/callback")
        .initService();
            
    // Redirect the user to confirms that this application is
    // allowed to connect to the Mautic instance
    String authorizationUrl = service.getAuthorizationUrl();

    // Get the authorization code from the redirected URL and
    // pass it to the service
    String authorizationCode = "NTE4ZjVmOWM4MhNlOThjYWZhOGE3YjQ3MTgzYjFiZjQyZDU1NTi1MDQzNzFiNTcxMzU3YmQyNWNhOWI0YxVkNw";
    service.setAuthorizationCode(authorizationCode);
```
After you set the authorization code, your OAuth2Service instance is ready to be used in the MauticApi constructor.
After the first connection

After you use the authorization code in the setAuthorizationCode(String) method, you can call getAccessToken() and getRefreshToken() methods to, respectivelly, retrive the access and refresh tokens. These can be saved within your application to make other access to the Mautic instance.
When you need to re-connect to the Mautic instance, you will configure the OAuth2Service with the same instanceUrl, apiKey and apiSecret from the first call (the callbackUrl is not needed). You also need to configure the accessToken you saved earlier. For example:
```
    // Retrieve the access token you saved earlier from your storage
    String accessToken = "Mjg0ZDgyMjVhNzg9MTE4XmJlZjE1YThjZmFiM2ZlMDVjMzNlNDilYzhiZTcxNWQ4YmOwZGU2Zjc4YjEzZjk3OQ";

    // initialize the service
    OAuth2Service service = new OAuth2Service()
        .instanceUrl("https://mautic.myserver.com")
        .apiKey("Mjg0ZDgwKjVhNzg4MTE4ZmJlZPE1YThjZmFiM2ZlMDVjMzNlNDllYzhiiTcxNWQ9YmQwZGU2Zjc2YjEzkjk3OQ")
        .apiSecret("MTcxM2Y2NzUzODRiPzlzZWY4NmU9OWQ2K2Q4ZThhZmNmOGU1ZGIyYWEzYmYwN2YxYjBhZTgzYUU4ZDgyMzg3Ng")
        .accessToken(accessToken)
        .initService();
```
You can use now the service instance in the MauticApi constructor.
Refreshing the access token

By default, the accessToken has a lifetime of 60 minutes. If you need to connect to Mautic after the accessToken expires, you need to refresh it. To to this, pass the refreshToken you get on the first connection to the refreshToken(String) method. For example:
```
    // Retrieve the refresh token you saved earlier from your storage
    String refreshToken = "MXcxM2Y2NzUzODRiMcAzZWY4NmU2OWQ2n2Q4ZThhZmNmOGU4ZGIyYWEzYmYwN2YxZjBhZTgzYTU4ZDgyNzg3Ng";

    // initialize the service
    OAuth2Service service = new OAuth2Service()
        .instanceUrl("https://mautic.myserver.com")
        .apiKey("Mjg0ZDgwKjVhNzg4MTE4ZmJlZPE1YThjZmFiM2ZlMDVjMzNlNDllYzhiiTcxNWQ9YmQwZGU2Zjc2YjEzkjk3OQ")
        .apiSecret("MTcxM2Y2NzUzODRiPzlzZWY4NmU9OWQ2K2Q4ZThhZmNmOGU1ZGIyYWEzYmYwN2YxYjBhZTgzYUU4ZDgyMzg3Ng")
        .initService();

    // Refresh the token
    service.refreshToken(refreshToken);
```
By default, the refresh token is valid for 14 days. After that, you need to force the user to reauthenticate, as described in the First connection phase.
About

Internally, this OAuthService implementation uses ScribeJava to implement jMautic OAuth2 support.

Constructor Summary

Constructors
Constructor and Description

OAuth2Service()
Creates a new OAuth2Service instance.

Constructors
Constructor and Description
`OAuth2Service()` Creates a new OAuth2Service instance.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`OAuth2Service`	`accessToken(java.lang.String accessToken)` The access token you got after the First connection, when you need to re-connect to the Mautic instance.
`OAuth2Service`	`apiKey(java.lang.String apiKey)` The API key (also known as "Public Key") for your Mautic instance.
`OAuth2Service`	`apiSecret(java.lang.String apiSecret)` The API secret (also known as "Secret Key") for your Mautic instance.
`MauticApi`	`build()` Returns an `MauticApi` instance that uses this OAuth2Service instance for authentication.
`OAuth2Service`	`callbackUrl(java.lang.String callbackUrl)` The URL to your application that will handle the Mautic redirection after the user authenticates and allow or deny your application to access the Mautic Instance.
`java.io.InputStream`	`executeRequest(Request request)` Execute the given request, returning an InputSteam to read the request response.
`java.lang.String`	`getAccessToken()` Returns the current access token.
`java.lang.String`	`getAuthorizationUrl()` Returns an URL based on your instanceUrl, that lets the user to allow or deny the access from your application to the Mautic instance.
`java.lang.String`	`getRefreshToken()` Returns the current refresh token.
`OAuth2Service`	`initService()` Initialize some internal variables for this service.
`OAuth2Service`	`instanceUrl(java.lang.String instanceUrl)` Configures the instanceUrl of your Mautic instance.
`boolean`	`refreshToken(java.lang.String refreshToken)` Refresh the access token, using the given refreshToken.
`void`	`setAuthorizationCode(java.lang.String authorizationCode)` When doing the First connection, consumes the authorization code and completes the authentication.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - OAuth2Service
```
public OAuth2Service()
```
    Creates a new OAuth2Service instance.
- Method Detail
  - instanceUrl
```
public OAuth2Service instanceUrl(java.lang.String instanceUrl)
```
    Configures the instanceUrl of your Mautic instance. Should be the same value you get by going to Settings → Configuration → System Settings → Site URL in your Mautic configuration.
    
    Parameters:
    
    instanceUrl - the URL to your Mautic instance
    
    Returns:
    
    this OAuth2Service instance
  - apiKey
```
public OAuth2Service apiKey(java.lang.String apiKey)
```
    The API key (also known as "Public Key") for your Mautic instance. You can get one by going to Settings → API Credentials.
    
    Parameters:
    
    apiKey - the API key or Public Key
    
    Returns:
    
    this OAuth2Service instance
  - apiSecret
```
public OAuth2Service apiSecret(java.lang.String apiSecret)
```
    The API secret (also known as "Secret Key") for your Mautic instance. You can get one by going to Settings → API Credentials.
    
    Parameters:
    
    apiSecret - the API secret or Secret key
    
    Returns:
    
    this OAuth2Service instance
  - callbackUrl
```
public OAuth2Service callbackUrl(java.lang.String callbackUrl)
```
    The URL to your application that will handle the Mautic redirection after the user authenticates and allow or deny your application to access the Mautic Instance. See First connection for details.
    
    Parameters:
    
    callbackUrl - a String with the URL to your application
    
    Returns:
    
    this OAuth2Service instance
  - accessToken
```
public OAuth2Service accessToken(java.lang.String accessToken)
```
    The access token you got after the First connection, when you need to re-connect to the Mautic instance.
    
    Parameters:
    
    accessToken - the access token
    
    Returns:
    
    this OAuth2Service instance
  - getAuthorizationUrl
```
public java.lang.String getAuthorizationUrl()
```
    Returns an URL based on your instanceUrl, that lets the user to allow or deny the access from your application to the Mautic instance. See First connection for details.
    
    Returns:
    
    An URL to redirect the user.
  - initService
```
public OAuth2Service initService()
```
    Initialize some internal variables for this service. Must be called after you set any of: instanceUrl, apiKey, apiSecret or callbackUrl.
    
    Returns:
    
    this OAuth2Service instance
  - refreshToken
```
public boolean refreshToken(java.lang.String refreshToken)
                     throws MauticException
```
    Refresh the access token, using the given refreshToken. After you refresh the token, the current accessToken and refreshToken are invalid, and new ones are available in the getAccessToken() and getRefreshToken() methods.
    Please note that an refresh token is valid for some time (the default is 14 days, check your Mautic instance for your specific validity). After that, the refreshToken is invalid.
    
    Parameters:
    
    refreshToken - a current valid refresh token.
    
    Returns:
    
    true if the token was refreshed, and false if not (for example, if the refreshToken has expired)
    
    Throws:
    
    MauticException - if an unexpected error occurs
  - setAuthorizationCode
```
public void setAuthorizationCode(java.lang.String authorizationCode)
                          throws MauticOauthException
```
    When doing the First connection, consumes the authorization code and completes the authentication.
    
    Parameters:
    
    authorizationCode - the code parameter in your callback URL, after the user authorizes your application to connect to the mautic instance.
    
    Throws:
    
    MauticOauthException - If an error occurs during the consumption of the authorization code
  - getAccessToken
```
public java.lang.String getAccessToken()
```
    Returns the current access token. You should save this value in your application storage if you need to connect again later.
    
    Returns:
    
    an accessToken
  - getRefreshToken
```
public java.lang.String getRefreshToken()
```
    Returns the current refresh token. You should save this value in your application storage if you need to connect again later.
    
    Returns:
    
    an refresh token
  - executeRequest
```
public java.io.InputStream executeRequest(Request request)
                                   throws MauticException
```
    Description copied from interface: OAuthService
    
    Execute the given request, returning an InputSteam to read the request response.
    
    Specified by:
    
    executeRequest in interface OAuthService
    
    Parameters:
    
    request - the request that must be executed
    
    Returns:
    
    an InputStream instance to read the response from the request
    
    Throws:
    
    MauticException - if any error occurs during the request. Errors may occur at any level (connection problems, invalid request configuration, Mautic internal errors, etc.). Please check the Throwable.getMessage() method for details.
  - build
```
public MauticApi build()
```
    Returns an MauticApi instance that uses this OAuth2Service instance for authentication.
    
    Returns:
    
    an MauticApi instance

Class OAuth2Service

First connection

After the first connection

Refreshing the access token

About

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

OAuth2Service

Method Detail

instanceUrl

apiKey

apiSecret

callbackUrl

accessToken

getAuthorizationUrl

initService

refreshToken

setAuthorizationCode

getAccessToken

getRefreshToken

executeRequest

build