Getting Started With OAuth2

Note: If you are needing an API key for an integration you purchased, please see our help documentation. This documentation is intended for app developers. 

Getting Started With OAuth2

Infusionsoft & OAuth 2.0

The Infusionsoft XML-RPC API uses a fairly standard implementation of OAuth 2.0 in order to provide authentication to all API endpoints. In the past, the Infusionsoft API has relied on a simple token based system; while those tokens will remain active until some date in the future, any new implementations will be required to use OAuth for all requests.

Rather than re-explain OAuth again, it is more useful to provide a series of documents that have already been created and demonstrate the OAuth protocol, how to implement it in your code, how to troubleshoot, and how to ease development. Before that, though, it is important to have the authorization destinations and necessary details.

Getting Started

You can create and manage your Infusionsoft applications to be used with OAuth in the portal by visiting the API Keys page. Using the client ID and client secret for your application, you can start the OAuth process to authenticate your users.

Redirect User to Authorization Endpoint

The first step in the OAuth flow is to redirect the user to Infusionsoft in order to authorize your application for access.

GET https://signin.infusionsoft.com/app/oauth/authorize

Request Parameters

Parameter Required Description
client_id required Application client ID
redirect_uri required This is the callback URL that Infusionsoft will redirect the users back to after authorization (must be HTTPS)
response_type required The desired grant type, as per the OAuth 2.0 spec. The only current valid value is response_type=code
scope The scopes required by your application. The only current valid value is scope=full

The redirect_uri must be a registered URL in your application. We will not redirect users to any other URLs, so it is important this be properly setup before any authentication attempts.

PHP SDK Example

$infusionsoft = new \Infusionsoft\Infusionsoft(array(
    'clientId' => 'CLIENTID',
    'clientSecret' => 'CLIENTSECRET',
    'redirectUri' => 'https://example.com/callback',
));

echo '<a href="' . $infusionsoft->getAuthorizationUrl() . '">Authorize with Infusionsoft</a>';

User Redirected Back to Application

Once the user has logged into their Infusionsoft account and authorized your application, they will be redirected back to your application at your specified redirect_uri with a code URL parameter that is used to request an access token.

GET https://example.com/callback?code={authorization_code}

If an error occurred while authorizing the application, the user is returned with the following parameters:

Parameter Description
error The type of error that has occurred (ex: access_denied)
error_description A short description of what went wrong
error_uri A URL to the relevant section in the documentation

Requesting an Access Token

Using the code URL parameter, your application can request an access token and refresh token from Infusionsoft.

POST https://api.infusionsoft.com/token

NOTE: The parameters below must be sent as form-urlencoded

Request Parameters

Parameter Required Description
client_id required Application client ID
client_secret required Application client secret
code required The code returned when the user is redirected back to your application
grant_type required The desired grant type, as per the OAuth 2.0 spec. The only current valid value is grant_type=authorization_code
redirect_uri required This is the redirect URL from the original authorization request

Response

{
    "token_type": "bearer",
    "access_token": "c6lvewpoz8uinazzudt4dayr",
    "expires_in": 28800,
    "refresh_token": "ndpgqhct7gucd8hgbhu6uhbl",
    "scope":"full|example.infusionsoft.com"
}

The access_token is the token you will use to authenticate requests to the Infusionsoft API, and it expires after the time in the expires_in field (in seconds). In order to get a new valid access token after one has expired, you must use the refresh_token.

PHP SDK Example

$infusionsoft = new \Infusionsoft\Infusionsoft(array(
    'clientId' => 'CLIENTID',
    'clientSecret' => 'CLIENTSECRET',
    'redirectUri' => 'https://example.com/callback',
));

if (isset($_GET['code'])) {
    return $infusionsoft->requestAccessToken($_GET['code']);
}

Refreshing Access Tokens

NOTE: Once a Refresh Token is used to receive a new Access Token, you will be returned a new Refresh Token as well, which will need to be persisted in order to request the next access token.

POST https://api.infusionsoft.com/token

Request Headers

Header Required Description
Authorization required A base64 encoded string of the format: Basic CLIENT_ID:CLIENT_SECRET

Request Parameters

Parameter Required Description
grant_type required The desired grant type, as per the OAuth 2.0 spec. The only current valid value is grant_type=refresh_token
refresh_token required The refresh token returned during the original authorization

Response

{
    "token_type": "bearer",
    "access_token": "c6lvewpoz8uinazzudt4dayr",
    "expires_in": 28800,
    "refresh_token": "ndpgqhct7gucd8hgbhu6uhbl",
    "scope":"full|example.infusionsoft.com"
}

PHP SDK Example

$infusionsoft = new \Infusionsoft\Infusionsoft(array(
    'clientId' => 'CLIENTID',
    'clientSecret' => 'CLIENTSECRET',
    'redirectUri' => 'https://example.com/callback',
));

// $storedToken is a token fetched from storage, such as session or database
$infusionsoft->setToken($storedToken);

return $infusionsoft->refreshAccessToken();

Making A Request

Once a user has gone through the OAuth flow, you can now make an Infusionsoft request on their behalf. You simply need to include a valid access token in the URL parameters of the request.

POST https://api.infusionsoft.com/crm/xmlrpc/v1?access_token=c6lvewpoz8uinazzudt4dayr

A Note on the API Key Field

In your final request to a method, you must still include the API key field in your XML-RPC request. This can be any value, so something such as your access token is perfectly appropriate.

The official Infusionsoft SDKs will automatically insert this extra parameter for you.

Example Request

POST https://api.infusionsoft.com/crm/xmlrpc/v1?access_token={access_token}

<?xml version='1.0' encoding='UTF-8'?>
<methodCall>
    <methodName>ContactService.add</methodName>
    <params>
        <param>
            <value><string>privateKey</string></value>
        </param>
        <param>
            <value><struct>
                <member><name>FirstName</name>
                    <value><string>John</string></value>
                </member>
                <member><name>LastName</name>
                    <value><string>Doe</string></value>
                </member>
                <member><name>Email</name>
                    <value><string>johndoe@example.com</string></value>
                </member>
            </struct></value>
        </param>
    </params>
</methodCall>

Resources

Check out the Official OAuth2 website to learn more about the protocol and how it works.

Test out your requests in IO Docs which will handle token negotiation for you.

Generate tokens with Runscope's fantastic Token Generator and then use Runscope to assist in debugging your API requests within your application.

If you're using the Infusionsoft PHP library, you can start using a version of the PHP SDK with OAuth.