OAuth Documentation

There are two options for your application to gain initial authorization access to an account.

• For integrations that you develop in-house, where you have direct access to user account credentials, we recommendgrant type: password.
• For integrations that you develop as a third party, where you can't store user credentials within the application, and/or where you connect to several accounts, we recommendgrant type: code.

Both authorization methods returns anaccess_tokenand arefresh_token. The access token is used with all other endpoints to verify your application has been authorized to access that account. The refresh_token is used only in thegrant type: refreshcall to the token endpoint. This provides a new pair of access and refresh tokens so that your session can continue uninterrupted.

About the Tokens

Each access_token expires 1 hour after the time it was granted. To continue using after a session access token expires, you must request a new one using the grant-type: refresh. Each refresh token can only be used once, and lasts either until it is used, or another access token is issued for the same application and username combination.

Password or Code grant types are limited to 5 authentication attempts per hour. Using the refresh token workflow avoids unneeded access token requests and prevents your application from reaching this limit. For more limits details, pleasesee our FAQ.

If you have an Act-On Agency account, please see ourAgency Authenticationpage for details on determining the username and setting the password for your agency's child accounts.

Getting Started

1. If you have not yet registered for a client ID and Secret, head to ourProvisioningpage to sign up.
2. Decide whether you will use thePasswordorCodegrant types.

Even if you plan to use grant type code, an understanding of how grant type password works can be useful.

In general, the authentication portions of your application should:

• Store the returnedaccess_tokento use to authenticate all other endpoint requests until the token expires.
• Store the returnedrefresh_tokenfor the purpose of getting a newaccess_tokenafter the access token expires.
• Use the refresh token from the immediately prior session in a refresh request. When the refresh request is granted, the response contains another access token/refresh token pair which will need to be stored for the next cycle.