OAuth

OAuth

Prerequisites

Before you start coding an OAuth implementation for your integration, you need to make a few decisions and preparations:

  • Decide whether you need code or password authentication.
  • Have available the client id and secret provided when you registered with the Act-On Developer community.
  • If you'd like to use any java code samples we provide for trying out our APIs (including the one at the end of this topic), first download the java unirest library from unirest.io.

Password or code authentication?

  • For integrations that you develop in-house, where you have direct access to user account credentials, we recommend password authentication.
  • 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 code authentication.

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

Client id and secret

As a member of the Act-On developer community, you have a client id and secret that was sent to you when you registered (if you have problems finding them, go to https://developer.act-on.com/provision/). Use the client id and secret for all of your session access requests.

Session access and refresh requests

Your code needs to observe the basic OAuth 2.0 patterns for authentication and access as follows:

  • An initial session access request must contain the client ID and secret in addition to individual user credentials.
  • A response to a successful access request contains a session access token and a refresh token.
  • Each session access token counts down from 3600 seconds.
  • To continue using Act-On after a session access token expires, you must send a request that contains a refresh token with no prior use.
  • Each refresh token can only be used once and lasts until another refresh grant is issued for the same Act-On user/client ID pair.

Grant Type Password

POST requests for grant type password to the the token endpoint:

using the following properties:

name value
grant_type password
username {Act-On user (email address)}
password {Act-On user password}
client_id {client_id}
client_secret {client_secret}

Example HTTP request

NOTE: replace the placeholder text in brackets with your client id and password.

Example curl requests

NOTE: replace the placeholder text in brackets with your client id and password.

Example response when using grant_type password :

oauth_pwd

Grant type code

With grant_type code, the end user's valid login request causes a redirect to a page that requests an authorization from them. When they respond by clicking Yes, your application should then forward valid credentials:

The response containing the grant code is sent to your redirect URL.
The default setting for the redirect is http://localhost. If you have not yet re-configured this please email us at api@act-on.com for a new URL.
The "state" parameter is optional and will be returned as passed by the request to your callback URL. This allows for session tracking.
A response will look like the following:
POST the code from the above response to the token endpoint to obtain session access and refresh tokens:
Name Value Notes
code {grant_code} Returned to your callback URL from the previous request
client_id {client_id}
client_secret {client_secret}
redirect_uri {your_redirect URI}
grant_type authorization_code

Example HTTP request

NOTE: replace the placeholder text in brackets with your code, client ID and client secret.

Example curl request

Following is a sample curl request.

NOTE: replace the placeholder text in brackets with your code, client ID and client secret.

The response is just like the response for password grant type:

Your code needs to:

  • Store the returned access token for the purpose of authenticating subsequent non-authorization requests until the token expires. (3600 seconds)
  • Store the returned refresh token for the purpose of getting a new access token after the access token expires.
  • Use the access token for all non-authentication related requests as specified by documentation for endpoints you are using. Access tokens expire in 3600 seconds.
  • To refresh a session, use the refresh token from the immediate prior session in a refresh request. When the refresh request is granted, the response contains another access token/refresh token pair.

The refresh token does not expire until a new initial access token request or a refresh request occurs.

Access token requests are limited to 5 per hour. Using this workflow avoids unneeded access token requests and prevents your application from reaching this limit.

Refresh request

POST to the token endpoint:

name value
refresh_token {saved refresh token}
grant_type refresh_token
client_id {client_id}
client_secret {client_secret}

Example HTTP request

NOTE: replace the placeholder text in brackets with your refresh token, client ID and client secret.

Example curl request

NOTE: replace the placeholder text in brackets with your refresh token, client ID and client secret.

An example response from a grant_type of refresh_token is:

Using refresh tokens to continue sessions allows you to avoid re-issue of password or code grant type request, which are limited to 5 per hour.

Code Examples

These examples use the java unirest library available at unirest.io. You can also find unirest libraries for node, ruby, php, java, objective c, python, and .net.

Java

OAuth
Grant Type Password
Grant Type Code
Grant Type Refresh
Account API
Get account information
Create new account user
Delete account users
Delete account user
Get email senders
Fact API
Upload custom events
Get upload custom event status
List API
Get listing of lists
Download a list
Create a new list
Update or merge a list
Get list upload status
Get rejected records from an upload
Delete a list
Delete records from a list
Get hard bounce list
Get spam complaint list
Get optout list
Update optout list
Get subscription opt-outs by category
mergespecs
uploadspecs
Content API
Get logo list
Get a logo
Add a logo
Update a logo
Delete a logo
Get header list
Get a header
Add a header
Update a header
Delete a header
Get footer list
Get a footer
Add a new footer
Delete a footer
Update a footer
Get image list
Get an image
Add an image
Replace an image
Delete an image
Get media list
Get media file
Add a media file
Add a media link
Update Media File
Delete a media object
Get form list
Get promotional form URLs
Get page list
Get page
Delete page
Get promotional page URLs
Get list of programs
Reporting API
Get message report
Get message report drilldown
Get message report by time period
Get media report
Get media message report
Get a media view report
Get a media timeline report
Get form report
Get page report
Get spam complaint list
Get hard bounce list
Email Campaign API
Get message list
Send a message
Resend a message
Add new template or draft message
Update template or draft message
Delete a message
Get message report
Get message report drilldown
Get message report by time period
Get message HTML contents
Contact API
Add a contact
Get contact record
Upsert a contact record by email
Update a contact by record ID
Delete a contact
Get contact record ID based on cookie value
Get contact from list based on cookie ID or e-mail
Get contact fact and score data
Get subscription categories
Opt in/Opt out subscription category by email address
Get subscription category opt-ins by email
Opt in/Opt out multiple subscription categories by email address
SEO API
Get SEO keywords
Get a new SEO report
Frequently Asked Questions