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

Before you start adding subscribers, sending messages, or checking your broadcast stats with AWeber’s API you’ll need to obtain access tokens for an AWeber account in order to make requests. We currently use OAuth 2 to verify that an integration is who they claim to be and has proper permission to access an AWeber account. New integrations should use OAuth 2, please refer to the guide linked above if you need a walkthrough.

However if your integration predates our release of OAuth 2 in April of 2019, you might be using OAuth 1.0a instead. We encourage you to move to OAuth 2 as soon as possible, but you can refer to this guide if you need to review the OAuth 1.0a flow in the meantime.

You’ll need the following to get started:

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

If you need a customer account you can sign up for a free trial to get started. These examples will be using Python 3 and requests_oauthlib as the HTTP library but there are lots of other good libraries out there.

Just looking for the endpoints and don’t need a walkthrough? No problem! Our authorization endpoints are listed below:

Request Token URL:

https://auth.aweber.com/1.0/oauth/request_token

Authorization URL:

https://auth.aweber.com/1.0/oauth/authorize

Access Token URL:

https://auth.aweber.com/1.0/oauth/access_token

 There is an archived version of our legacy OAuth 1 documentation, including details on distributed authorization for WordPress plugins, available from web archive.

What is OAuth 1a?

In a nutshell, OAuth is basically a way for a developer to securely access information without knowing someone’s password or other login details. The end result of following the OAuth 1 process is a set of access tokens.The access tokens prove the developer has permission to access the data held within the API and should always be kept safe and secure. When OAuth 1 is used the user never has to share their password with the developer, which is good for security.

If you’ve never used OAuth 1.0a before it can be a little intimidating, but don’t worry because this guide will walk you through each step. You’ll learn to do the following:

1. Generate a request token
2. Authorize that request token to get a verifier
3. Trade the request token and verifier to get access tokens

Step 1: Generating a request token

First, you’ll need to tell AWeber’s API that someone would like to authorize your integration to access their account. The request token and secret, sometimes called OAuth tokens, are the way to do that. Find your integration’s consumer key and secret in your Labs account. It’ll be on the right, below the edit button. Do not share these keys with anyone (that includes leaving them in code you post publicly, like a WordPress plugin, JavaScript on your site, or code you make open source)! If you have a distributed plugin or integration or need to share the source code you can use our distributed auth flow, which uses the app ID instead of the consumer key and secret.

Once you have those keys you can use your library to make a GET request to https://auth.aweber.com/1.0/oauth/request_token, which is AWeber’s request token endpoint.

We also need to specify a callback URL that will allow us to obtain a verifier token. If you don’t have a web page to capture the verifier you can use “oob” instead, which will just display the token to the user after they sign in successfully. The “oob” stands for out of band, which just means you’re working outside of a web browser.

Here’s an example with requests_oauthlib:

from requests_oauthlib import OAuth1Session, OAuth1

# Replace with your real keys
consumer_key = '****'
consumer_secret = '****

request_token_url = 'https://auth.aweber.com/1.0/oauth/request_token'
oauth = OAuth1Session(consumer_key, consumer_secret, callback_uri='oob') 
fetch_response = oauth.fetch_request_token(request_token_url)

request_token = fetch_response.get('oauth_token')
request_secret = fetch_response.get('oauth_token_secret')

The response will contain your request token and secret that will be used in the next steps.

Step 2: Authorizing the request token

Once the request token and secret are obtained the next step is getting permission from the user to access their account. To do this, you’ll ask the user to go to https://auth.aweber.com/1.0/oauth/authorize?oauth_token=XXX, where “XXX” is the request token you obtained in step 1.

That URL is a special web page that shows a login box. If you’re authorizing your own AWeber account be sure to put your customer account information in there and not your developer account information. They are two separate logins. If you’re authorizing someone else’s account you’ll need to send them the link and ask them to log in to allow your integration access.

Note the small bullet points in the picture below will change depending on what permissions you have enabled.

Once the user successfully enters their AWeber login information AWeber will redirect them to the callback you defined in step 1 and provide a verifier token that you can use for the next step. If that callback was a page on your website the verifier will be in the query string like so:

{your_callback}/?oauth_token=******************&oauth_verifier=******&display=page

If you used “oob” as your callback as in the example in step 1 the verifier will be shown to the user. This is helpful when you’re trying to authorize your own account, though you can instruct the user to copy and paste it somewhere if you like.

Step 3: Trade for Access Tokens

Now you need to combine the request token and secret and your newly obtained verifier and trade them for a permanent access token and secret. These are the keys you’ll use to access the user’s AWeber account.

Note: Protect the access tokens like you would your own passwords. They give you access to the account of the AWeber customer who authorized your app and will remain valid until they revoke that access or until you change your consumer key and secret. Store them safely!

To make the trade, just make one final POST request to https://auth.aweber.com/1.0/oauth/access_token, which is AWeber’s access token endpoint. The response will contain your access token and secret and you can make all the API calls you wish!

Here’s a requests_oauthlib example, using the same OAuth1Session that was set up in the first step:

access_token_url = 'https://auth.aweber.com/1.0/oauth/access_token'
authkeys = OAuth1(client_key = consumer_key, 
                  client_secret = consumer_secret, 
                  resource_owner_key = oauth_token,
                  resource_owner_secret = oauth_secret,
                  verifier = oauth_verifier)

access_response = oauth.fetch_access_token(access_token_url, verifier=oauth_verifier, auth=authkeys)

access_token = access_response.get('oauth_token')
access_secret = access_response.get('oauth_token_secret')

Use your access tokens in combination with your consumer key and secret to make API calls! You might want to get your account ID first. Your new access tokens will never expire, but they can be revoked from the AWeber customer’s side by hitting the “disable” button in their account or you can revoke all of them at once by changing your consumer key.

Have more than one user?

Sometimes an integration is used by many AWeber customers. You can have as many users as you like with this authentication process. Just start at the top and make a new request token for each user of your integration. Access tokens are tied to AWeber customer accounts so each account will have a new set of tokens. You can store them safely in a database and use the account ID to differentiate them.

Having trouble?

Never fear! We’re always ready to help you. Send an email to api@aweber.com and let us know where you’re getting stuck.

There are a few common problems you can check for as well:

• Is your app an OAuth 2 app instead of OAuth 1.0a? If you aren't sure the authentication method will be listed by your app's name in your developer account. OAuth 2 apps also have a client ID instead of a consumer key.
• For OAuth 1.0a authentication like this, make sure to use the consumer key listed in your developer account.
• The OAuth1.0a described here does not require an authorization code.
• Make sure the AWeber account login information is valid by trying to log in at https://www.aweber.com/login.htm. If you cannot log in there, try resetting your password.
• Make sure you’re not using your developer account login for the authorize login page.
• Make sure your consumer key and secret are correctly typed or copy/pasted when you get request tokens.
• Check the documentation for your HTTP library and make sure it supports OAuth 1.0a. Many libraries have walkthroughs of the workflow in their documentation as well.