OAuth2 (Open Authorization) is an authorization protocol that notifies GetResponse that your application can access data in other GetResponse accounts. For example, you’ve written an application “MyTemplateMaker”. Your client has a GetResponse account and wants to integrate it with your application. For this to happen, you need to register your app with GetResponse and make it possible for the client to authorize your application to access their account and data.

Note:

  • This is a first steps document that explains how to use the Authorization Code authorization method. For a comprehensive discussion of OAuth2 methods, go to documentation.

  • We suggest you don’t implement OAuth from scratch in your application. Instead, you should use a third-party library appropriate to your system architecture, e.g. for PHP with provider, Ruby, or Python.

Register application and obtain authorization data

  1. Visit Add new application in GetResponse WWW
  2. Enter a name, description, and logo of your application. Next, enter a Redirect URL. This is the URL to which GetResponse will redirect your client during the authorization process. This should be an URL in your domain, for example: https://mytemplatemaker.example.com/gr_callback
  3. Click Add.

Your registered app will appear under Connected applications. Click on the app name to display:

  • Client ID - This is the “application username”. It identifies your application in the GetResponse system.
  • Client secret key - This is the “application password”. This key should be strictly confidential and protected.

You need these parameters to obtain the authorization token.

When your client wants to use their GetResponse account, your application should redirect them to the following URL. Be sure to replace client_ID with your Client ID value and random_string with any random string (this is for security reasons):

https://app.getresponse.com/oauth2_authorize.html?response_type=code&client_id=client_ID_&state=random_string

Once redirected to the GetResponse panel, your client will have to log into their account and confirm your application’s permissions to access it. Finally, they will be redirected to the URL you set during the application registration, for example:

https://mytemplatemaker.example.com/gr_callback?code=ed17c498bfe343175cd7684c5b09979f2875b25c&state=random_string

You have to handle this request. random_string should be equal to the one you sent with the first redirect. code is the authorization code you will have to exchange for the token.

Exchange code for access token

You will have to get the token by calling:

curl -u client_id:client_secret https://api.getresponse.com/v3/token \
        -d "grant_type=authorization_code&code=ed17c498bfe343175cd7684c5b09979f2875b25c"

Replace client_id and client_secret with the values you received while registering your application. authorization_code is the code from the previous (second) redirect.

As a response, you will receive:

{
    "access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null,
    "refresh_token": "170d9f64e781aaa6b3ba036083faba71b2fc4e6c"
}

Now you can make a request to API, for example:

curl -H "Authorization: Bearer 03807cb390319329bdf6c777d4dfae9c0d3b3c35" https://api.getresponse.com/v3/from-fields

Refresh token

The token is valid for a limited time: expires_in value (in seconds). When the token expires, you will receive a 401 response:

{
    "httpStatus": 401,
    "code": 1014,
    "codeDescription": "Problem during authentication process, check headers!",
    "message": "The access token provided is expired",
    "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1014",
    "context": {
        "sentToken": "03807cb390319329bdf6c777d4dfae9c0d3b3c35"
    }
}

To refresh the token you will have to make a request using the refresh_token value you received when obtaining the token. Example request:

curl -u client_id:client_secret https://api.getresponse.com/v3/token \
       -d 'grant_type=refresh_token&refresh_token=170d9f64e781aaa6b3ba036083faba71b2fc4e6c'

As a response you will receive another access_token and refresh_token.

Note that the refresh_token also expires. If that happens, you will have to redirect your client to their account so that they can allow your application to access their account again.

Please refer to the API documentation for details. Note that there are some differences for GetResponse MAX accounts.