How do I use OAuth 2 authentication with AWeber's API?

Connecting your integration to an AWeber customer account requires the use of OAuth 2. This step is required before you start making requests to AWeber’s API in order to do things like add subscribers, check your broadcast stats, or sending messages. We use OAuth 2 in order to ensure that an integration has permission to access a given AWeber account.

You’ll need the following to get started:

• An AWeber developer account
• An OAuth 2 app created in that account
• An AWeber customer account
• An HTTP library capable of making OAuth 2 requests.

If you need a customer account you can sign up for a free trial to get started. The example in this document is using Python 3 and requests_oauthlib as the HTTP library. You will find there are lots of good libraries available for every programming language. The set up and usage varies between libraries. Be sure to read the documentation for the library you select.

Do you just need the endpoints and not a whole walkthrough? Our authorization endpoints are listed below:

Authorize URL:

https://auth.aweber.com/oauth2/authorize

Access Token / Refresh Token URL:

https://auth.aweber.com/oauth2/token

What is OAuth 2?

OAuth is a way for a developer to securely access information without knowing someone’s password or other login details. The end result of OAuth is an access token, which prove the developer has permission to access the data held in the API and should always be kept safe and secure.

OAuth 2 is the successor to OAuth 1, which AWeber’s API formerly used. If you have an existing OAuth 1 application, documentation regarding how to connect with OAuth 1 is available. Please plan to move to OAuth 2 as soon as you are able.

The general flow of OAuth 2 is a back and forth handshake between the developer, the AWeber customer, and AWeber’s API. In this guide you’ll learn to do the following:

1. Build an authorization URL
2. Get an authorization code
3. Trade your authorization code for an access token
4. Refresh your access token after it expires using the refresh token

Step 1: Build an Authorization URL

The first thing you’ll need to do is create a hyperlink to start the authorization process. This code provides AWeber’s API with information such as which integration is making the request and what access the integration requires. Please review the example below:

  https://auth.aweber.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK&scope=YOUR_REQUESTED_SCOPES&state=STATE_TOKEN

The components of this URL are as follows:

• The base URL is provided by AWeber and connects you to our servers.
• response_type tells AWeber what you want us to send back. For this step you should always use “code” since you want an authorization code.
• client_id is the Client ID listed in your developer account. It uniquely identifies your integration to AWeber.
• redirect_uri is your callback. This is where the user-agent (in most cases the customer’s browser) will be sent after the customer clicks “authorize”. This should be a uri that your application can read because that’s where we’ll provide our response. When you provide your callback, make sure it’s the same one you specified when creating your integration.
• scope is a list of space separated permissions your integration requires. Check out our guide to scopes for a list. To change permissions later, all customers will need to repeat the authorization process. Please ensure you have the ones you need.
• state is a token you provide to AWeber for CSRF protection. You can also use this token as a session token to preserve user data between the auth steps, providing a better experience for your users. We pass this data back to you later and you can check that it matches the value you sent. A random string or a hash of a session cookie is acceptable here, it just needs to be something you know but a potential attacker doesn’t and it should change for each new user.

Step 2: Get an Authorization Code

Using the authorization URL you generated in Step 1, create a button or hyperlink that says “Click to connect to AWeber” or something similar.

The link you provide will lead customers to AWeber’s authorization screen. This screen outlines your integration, the access being requested, and an area for customers to provide their username and password. Customers will review the screen, enter their login credentials, and click authorize.

Clicking authorize (after entering valid credentials) redirects the user to the callback URI you specified in Step 1. In the query string of the redirect will be a query parameter containing your authorization code. If you provided a state token in step 1, that is sent back as a second query parameter.

For example, if the redirect_uri you provided was https://app.example.com/auth we would redirect the AWeber customer’s browser to https://app.example.com/auth?code=YOUR_NEW_AUTH_CODE&state=STATE_YOU_PROVIDED

You should collect the query parameters from the URI. Please verify the state token sent to you is the same as the one you gave us. If everything is valid, save the code parameter for the next step. Your chosen library may handle verification of the state token for you.

Step 3: Trade your Authorization Code for an Access Token

Now that you have your authorization code you’re ready to get your access token! This involves making a POST request to our access token URL, https://auth.aweber.com/oauth2/token using your client ID and secret from your developer account. We recommend using HTTP Basic authentication with the client ID as the username and the client secret as the password. Most libraries support this approach. If yours doesn’t, please send them as query parameters called client_id and client_secret. Here’s what a POST request looks like using basic authentication:

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic
YOUR AUTHENTICATION

https://auth.aweber.com/oauth2/token
?grant_type=authorization_code
&code=YOUR_AUTHORIZATION_CODE
&redirect_uri=YOUR_CALLBACK

The parameters required are as follows:

• grant_type is a parameter that tells us if you’re getting a brand new access token or refreshing one. For a new token always pick “authorization_code”.
• code is the authorization code you obtained in step 2.
• redirect_uri is your callback again. Make sure it’s the same as the one you used before! We use this to help verify it’s still the same app making the request.

Our response will contain your access token, an expires_in value, and a refresh token. Congratulations, you now have the access token required to make requests to AWeber’s API! You can try it out right away, but make sure to save the expires_in and refresh token information for later. Tokens should not be shared publicly. Please save them somewhere safe.

To use the access token you must include it with your request using (in order of preference) a bearer authentication header, a form encoded parameter in the body, or a query parameter. Any of those three will work, but please choose one.

This access token remains good for one hour. After an hour you will need to refresh your token, which is covered in the final step of this walkthrough.

Step 4: Refresh the Access Token

If it’s been a while since you obtained your access token, all requests to AWeber’s API will return an unauthorized error. To correct the error, you need to refresh your access token. This step works much like obtaining an access token. You will make a POST request to AWeber’s token endpoint. This time specify a grant_type of “refresh_token” and you include your refresh token in the request (instead of the authorization code). Please review the example below:

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic
YOUR AUTHENTICATION

https://auth.aweber.com/oauth2/token
?grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN

The response is similar to the access token. You will receive a new token, an expires_in parameter, and a refresh token. This is required each time your token expires.

Most libraries manage refreshing tokens for you by reading the “expires_in” parameter from a file or database location. Please refer to your library’s documentation about automatic refreshing. The implementation may vary slightly. When using Python’s requests_oauthlib library the call looks like this, where ‘aweber’ is an OAuth2Session:

client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'

refresh_url = 'https://auth.aweber.com/oauth2/token'

token = aweber.refresh_token(refresh_url, 
                             client_id=client_id, 
                             client_secret=client_secret)

For more information on refreshing be sure to read our knowledge base article on the topic.

Authorization Example:

You can use Python 3 and requests_oauthlib to generate your tokens fairly easily. Other libraries and languages will have similar functionality and may look different. Please check the documentation!

from requests_oauthlib import OAuth2Session

client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'
redirect_uri = 'https://app.example.com/auth'

# Sample scopes. Put the ones you need here.
scope = ['account.read', 'list.read', 'subscriber.read']

authorization_base_url = 'https://auth.aweber.com/oauth2/authorize'
token_url = 'https://auth.aweber.com/oauth2/token'

# Create a new OAuth2Session with your information.
aweber = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=scope)

# requests_oauthlib generates a state token for us, 
# but you can optionally specify your own.
authorization_url, state = aweber.authorization_url(authorization_base_url)

# Open link in browser to authorize.
print("Go here to authorize: {}".format(authorization_url))

# Get the auth code from the callback.
redirect_response = input("Enter the full redirect URL: ")

# Use the auth code to get access tokens.
token = aweber.fetch_token(token_url, 
                           client_secret=client_secret
                           authorization_response=redirect_response)

print("Access Token: " + token['access_token'])
print("Refresh Token: " + token['refresh_token'])
print("Token Type: " + token['token_type'])
print("Expires In: " + token['expires_in'])
print("Expires At: " + token['expires_at'])

Having trouble?

Here are some solutions to common problems:

• Check the documentation for your chosen library. Are the calls being made correctly and is everything being passed around as it should be?
• Is your access token still valid? Try refreshing the token and see if that fixes any 401 Unauthorized errors.
• Did you copy your client ID and secret correctly? Make sure the ID and secret you’re using are the ones we provided in your developer account.
• Make sure you’re using your AWeber customer account and not your AWeber developer account on the authorization login page.

If you still can’t figure it out we’re always happy to help you work through any errors. Send us an email at api@aweber.com and be sure to note any errors or information about the problem you’re having.