There are two options for your application to gain initial authorization access to an Act-On account.
- For integrations that you develop in-house, where you have direct access to user account credentials, we recommend grant 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 Act-On accounts, we recommend grant type: code.
Both authorization methods returns an access_token and a refresh_token. The access token is used with all other endpoints to verify your application has been authorized to access that Act-On account. The refresh_token is used only in the grant type: refresh call 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 Act-On 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, please see our FAQ.
Getting Started
- If you have not yet registered for a client ID and Secret, please see Managing Child Accounts in the Marketing Network.
- Decide whether you will use the Password or Code grant 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 returned access_token to use to authenticate all other endpoint requests until the token expires.
- Store the returned refresh_token for the purpose of getting a new access_token after 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.
| Method Name | Endpoint | Description |
| Grant Type Password | POST /token | Request for access and refresh tokens using grant_type password |
| Grant Type Code | POST /token | Request for access and refresh tokens using grant_type code |
| Grant Type Refresh | POST /token | Request new access token after initial authentication |