This page describes how to get an access token and organizer key using the OAuth procedure. OAuth is a standardized method of authenticating users and authorizing third party applications for access to the authenticated user’s data or account across the Internet. The Developer Center uses OAuth 2.0. OAuth 2.0 is the industry-standard, best practice, authentication and authorization method.

IMPORTANT: This page reflects recent improvements (starting December 22, 2017) to the authentication flow including revised URLs and token expiration periods. See the OAuth Migration Guide for details.

IMPORTANT: If you want to get an access token for GoToAssist Corporate, see How to Use Direct Login.

IMPORTANT:  The GoTo APIs will enforce Transport Layer Security (TLS) version 1.2 by August 23, 2018. From then on, API calls only supporting TLS in version 1.0 or 1.1 will fail to connect.

REST API calls on the Developer Center require an access token. Access tokens are generated by the backend services when you send a request with a valid Consumer Key (Client ID) (see Creating a Developer Center App) and a valid user authentication.

There are several methods you can use to acquire and use an access token. These methods include:

1 - Request Authorization Code

Create an authorization request on behalf of a GoTo product user. It sends them to a product login page.

  1. Copy the Consumer Key value and insert the value into the following URL to replace {consumerKey}:
https://api.getgo.com/oauth/v2/authorize?client_id={consumerKey}&response_type=code

A redirect URI is a target URI where you post your authorization code, and which is then exchanged for an access token you can use to authenticate subsequent API calls.

To add a redirect URI, make sure the URI is defined in your application under MyApps.

IMPORTANT: The redirect_uri is required in the access token request if you include the redirect_uri parameter in the authorization request. Their values MUST be identical. If it is not included in the access token request, then any redirect_uri value passed in the authorization request is ignored and the first URL defined in the application under MyApps is used.

A redirect URL of http://example.com can support any of the following redirect URLs:

However, you must encode the URI:

  • http%3A%2F%2Fcode.example.com

You can also add a state parameter to the authorization call. This also validates the environment. The state value should return unchanged. If it is missing or corrupted, the OAuth transaction might be compromised. An example of the use of redirect URI and state:

https://api.getgo.com/oauth/v2/authorize?client_id={consumerKey}&response_type=code&state=MyTest&redirect_uri=http%3A%2F%2Fcode.example.com
  1. The user sends the URL. The user is directed to the sign-in page for the product.
  2. If they are not already logged in, they sign in with their credentials and must click Allow to allow access for the developer application. The user is then automatically redirected to the redirect URL you defined in the developer center application. The redirect URI has a Response Key added to it.
    IMPORTANT: You may see an error on the page such as 404 NOT FOUND. This is not a problem. Look at the URL in the browser. It contains the responseKey you need for the next step. It will look something like:
http://example.com/oauthreturn/?code={responseKey}

If you included a specific redirect URI and state, the response looks like:

http://code.example.com/return/from/oauth/?scope=&code={responseKey}&state=MyTest

2 - Request Access Token

You can now use the Response Key on behalf of this user to request an access token and other details about the user account.

IMPORTANT: Each responseKey can only be exchanged once. Any subsequent attempts will result in an error.

The allowed method for making the access token request is to use a POST call. You can use an API command line interface like cURL for this.

Curl syntax is shown to include the full request. Your request can be sent through an API client such as Postman, or through your client application.

curl -X POST "https://api.getgo.com/oauth/v2/token" \
  -H "Authorization: Basic {Base64 Encoded consumerKey and consumerSecret}" \
  -H "Accept:application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code={responseKey}&redirect_uri=http%3A%2F%2Fcode.example.com"

Authorization Header

The authorization header is gathered by base64-encoding the app's consumer key and consumer secret in the form "{consumerKey}:{consumerSecret}", e.g. via an online tool (like https://www.base64encode.org). Then final authorization header is then looking like "Authorization: Basic ZXhhbXBsZV9jbGllbnRfaWQ6ZXhhbXBsZV9jbGllbnRfc2VjcmV0"

POST Data Content

Parameter Description Format Required
grant_type string reading "authorization_code" string required
code responseKey from the redirect string required
redirect_uri target uri for authorization code string only required if given in /authorize call

Response Example

This returns an access token and user information:

{
 "access_token":"RlUe11faKeyCWxZToK3nk0uTKAL",
 "expires_in":3600,
 "token_type":"Bearer"
 "refresh_token":"d1cp20yB3hrFAKeTokenTr49EZ34kTvNK",
 "organizer_key":"8439885694023999999",
 "account_key":"9999982253621659654",
 "account_type":"",
 "firstName":"Mahar",
 "lastName":"Singh",
 "email":"mahar.singh@singhSong.com",
 "version":"3"
}

Response Data

Parameter Description
access_token OAuth access token
expires_in The access token's expiration time in seconds (60 minutes)
token_type The type of the access token (always "Bearer")
refresh_token The token to use to obtain a new access token, for example, if the current access token has expired. The refresh token is valid for 30 days.
How to Use Refresh Tokens describes how to use it.
organizer_key GoTo product user organizer key
account_key GoTo product account key (may be blank)
account_type GoTo product type “personal” or “corporate” (may be missing or blank)
firstName GoTo product user organizer first name (only G2M, missing or blank for other products)
lastName GoTo product user organizer last name (only G2M, missing or blank for other products)
email GoTo product user organizer email (only G2M, missing or blank for other products)
version The version of the access token

 

This access token can now be used to authorize API requests by setting it in the Authorization header with the following format: "Authorization: Bearer {access_token}".

E.g. for the GET /me request of the Admin API:

curl -H "Accept: application/json" -H "Authorization: Bearer RlUe11faKeyCWxZToK3nk0uTKAL" "https://api.getgo.com/admin/rest/v1/me"

You can also use the access_token and organizer_key values in the API Reference page for the product, or in API calls in your client application.