Config API Version 2 Oauth2

Introduction

Infinity integrates with several third party systems.

To do so, we need to authenticate against their own APIs with credentials and account references.

Each account requires credentials in order to access its data. Those credentials can be either basic auth (a username and password) or oAuth2 (a refresh token).

For oAuth2, you must first create an auth session, use that session key to grant access to Infinity for the given client’s data, then finally submit the session key to the appropriate create or update route.

The oAuth2 process is more complicated than basic auth but is considered more secure as the password and refresh token are kept private within each system.

Create oAuth2 Session

Creates a new authentication session using oAuth2. The authentication session will last for approx 10 minutes which should be long enough to link an account.

The returned authSessionKey should be stored for later use, and the end user should be directed to the returned authUri so they can grant or deny access.

Request:

POST /config/v2/oauth2/session

POST Params

returnUri (string) - The URI to return the end user to once authentication is complete.
appCode (string) - The appCode to identify the third party system.

This is a list of supported appCodes:

salesforce
salesforceSandbox
ds3
googleAdwords
bingAds
googleDcm

Response:

Returns details of the new authentication session. Returns a “201 - CREATED” response code to indicate success.

authSessionKey (string) - Unique identifier for the auth session - store this in e.g. a session cookie.
authUri (string) - The URI for the end user to grant (or deny) access - send the end user here so they can respond to the request once the session key has been stored.
returnUri (string) - The return URI provided in the create request - the end user will be returned here after they respond to the auth request.
appCode (string) - Identifies the third party system that we are authenticating against.
status (int) - The status of the auth session (e.g. 102 - new, 200 - access granted, 403 - access denied).

Response example:

HTTP 201 - CREATED
{
    "authSessionKey":"684ff80597a447ffb8656bb75c85fc0e",
    "authUri":"https:\/\/accounts.google.com\/o\/oauth2\/auth?access_type=offline&approval_prompt=force&client_id=13748250235-6289v45ihrs0dvekdqhr159841ss62le.apps.googleusercontent.com&scope=https%3A%2F%2Fadwords.google.com%2Fapi%2Fadwords%2F&response_type=code&state=684ff80597a447ffb8656bb75c85fc0e&redirect_uri=https%3A%2F%2Fapi.infinitycloud.com%2Fcallback%2Fv1%2Foauth2",
    "returnUri":"http:\/\/example.com\/",
    "appCode":"googleAdwords",
    "status":"102"
}

Read oAuth2 Session

Read details of an existing oAuth2 authentication session.

This may be useful to check the status of an existing session, before using it to manage accounts.

Note there are additional details of the session that are not shown here. This includes any access or refresh tokens, in order to keep them private.

Request:

GET /config/v2/oauth2/session/{authSessionKey}

URL Path Params

authSessionKey (string) - Unique identifier for the auth session.

Response:

Returns details of the existing authentication session. Returns a “200 - OK” response code to indicate success. If the session does not exist or has expired, a “404 - NOT FOUND” response will be returned with no data.

authSessionKey (string) - Unique identifier for the auth session, as provided in the request.
authUri (string) - The URI for the end user to grant (or deny) access - send the end user here so they can respond to the request.
returnUri (string) - The return URI provided in the create request.
appCode (string) - Identifies the third party system that we are authenticating against.
status (int) - The status of the auth session (e.g. 102 - new, 200 - access granted, 403 - access denied).

Response example:

HTTP 200 - OK
{
    "authSessionKey":"684ff80597a447ffb8656bb75c85fc0e",
    "authUri":"https:\/\/accounts.google.com\/o\/oauth2\/auth?access_type=offline&approval_prompt=force&client_id=13748250235-6289v45ihrs0dvekdqhr159841ss62le.apps.googleusercontent.com&scope=https%3A%2F%2Fadwords.google.com%2Fapi%2Fadwords%2F&response_type=code&state=684ff80597a447ffb8656bb75c85fc0e&redirect_uri=https%3A%2F%2Fapi.infinitycloud.com%2Fcallback%2Fv1%2Foauth2",
    "returnUri":"http:\/\/example.com\/",
    "appCode":"googleAdwords",
    "status":"200"
}