GoTo
Guides
Support
Changelog
API Status
GoTo

OAuth Migration Guide

This guide is to help external developers to migrate their app from the legacy OAuth proxy (https://api.getgo.com/oauth/) to the new OAuth proxy (https://api.getgo.com/oauth/v2/) which is fully compliant to the OAuth Standard (RFC 6749). Since many things changed, but the proxy is now fully OAuth V2 compliant, external 3rd party libraries for handling the access and refresh tokens can now be used.

Differences between Legacy and new RFC 6749 compliant OAuth Proxy

Legacy OAuth Proxy

https://api.getgo.com/oauth/

/authorize calls

Opening the URL https://api.getgo.com/oauth/authorize?client_id={consumerKey} in a web browser was already sufficient to start the Authentication Flow. A redirect_uri or state parameter could be given.

/access_token calls

Common Changes in the Request - Making a GET or POST request to https://api.getgo.com/oauth/access_token with the parameters or POST data grant_type={authorization_code|password|refresh_token}&client_id={consumerKey}&... will retrieve an access token and refresh token.

Common Changes in the Response - The response of a call to https://api.getgo.com/oauth/access_token was looking like:

{
    "access_token": "o4yGgdsjaklfjdsklfadiygQ9",
    "expires_in": "30758399",
    "refresh_token": "9i4fdasfdsfdsfdsavnUbDw1",
    "organizer_key": "1252383132521359990",
    "account_key": "3792314532151329654",
    "account_type": "",
    "firstName": "Jon",
    "lastName": "Karmak",
    "email": "jk@example.com",
    "platform": "GLOBAL",
    "version": "2"
}

Access token request

Making a GET or POST request to https://api.getgo.com/oauth/access_token with the parameters or POST data grant_type=authorization_code&code={responseKey}&client_id={consumerKey} will retrieve an access token and refresh token.

Direct login

Note: This action is only available for legacy clients. Making a GET or POST request to https://api.getgo.com/oauth/access_token with the parameters or POST data grant_type=password&user_id={username}&password={password}&client_id={consumerKey} will retrieve an access token and refresh token.

Refresh Token

Making a GET or POST request to https://api.getgo.com/oauth/access_token with the parameters or POST data grant_type=refresh_token&refresh_token={refresh_token}&client_id={consumerKey} will retrieve a new access token and refresh token.

Changes in New OAuth v2 Proxy

https://api.getgo.com/oauth/v2/

/authorize calls

The additional response_type=code parameter is required and needs to be added to the request:

https://api.getgo.com/oauth/v2/authorize?response_type=code&client_id={consumerKey}&state={state}

Hint: It is recommended to use the state parameter to prevent cross-site request forgery as described in the RFC-6749 Section 4.1.1.

/access_token calls

Common Changes in the Request - The proxy endpoint changed from /access_token to just /token:

https://api.getgo.com/oauth/v2/token

Only POST is supported and no GET. When switching from a GET to a POST request the POST content is urlencoded, you need the following header to set the correct content type:

"Content-Type: application/x-www-form-urlencoded"

This header replaces the previous header:

"Content-Type: application/json"

The POST body has to look like:

grant_type=authorization_code&code={responseKey}

This body replaces the query parameter used before. The client_id is no longer been given as a parameter. Instead, it has to be given as base64 encoded Authorization header, together with the client_secret:

curl -X POST \
  'https://api.getgo.com/oauth/v2/token' \
  -H 'Authorization: Basic {Base64 Encoded client_id and client_secret}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code={responseKey}'

This authentication header is gathered by base64-encoding the string "{clientid}:{clientsecret}", e.g. via an online tool (like https://www.base64encode.org/) or by calling the btoa method in JavaScript.

Common Changes in the Response - The response of a call to https://api.getgo.com/oauth/v2/token is looking like:

{
    "access_token": "o4yGgdsjaklfjdsklfadiygQ9",
    "token_type": "Bearer",
    "refresh_token": "9i4fdasfdsfdsfdsavnUbDw1",
    "expires_in": 3600,
    "account_key": "3792882212321659654",
    "account_type": "",
    "email": "jk@example.com",
    "firstName": "Jon",
    "lastName": "Karmak",
    "organizer_key": "18889842069694200",
    "version": "3"
}

The deprecated property platform is no longer there. The new variable token_type is there and set to "Bearer". The type of the expires_in is no longer a string. It is now an integer value. The expires_in parameter will be set to 3600 seconds. That means, that such an access token will only be valid for one hour and needs to be refreshed (by using the refresh token) in order to make further API calls. And version is now set to "3"

Access Token Request

All the common request and response changes above.

The redirect_uri parameter is (only) required, when it has been given in the /authorize call above. In this case, its value must match with what has been given in the /authorize call. If it hasn't been given in the /authorize call, it will be ignored.

curl -X POST \
  'https://api.getgo.com/oauth/v2/token' \
  -H 'Authorization: Basic {Base64 Encoded client_id and client_secret}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code={responseKey}'

Direct Login (Deprecated)

This authentication API is now deprecated. All new clients will not be able to use this API. If you have a client for which the direct login works, that will continue to work for now.

All the common request and response changes above.

The user_id parameter changed to username.

curl -X POST \
  'https://api.getgo.com/oauth/v2/token' \
  -H 'Authorization: Basic {Base64 Encoded client_id and client_secret}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username={username}&password={password}'

Refresh Token

All the common request and response changes above.

curl -X POST \
  'https://api.getgo.com/oauth/v2/token' \
  -H 'Authorization: Basic {Base64 Encoded client_id and client_secret}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&refresh_token={refresh_token}'