I Have the Power: Agency Level API Access

This post only applies to Legacy Version 3 of the API

So far, most of the API examples and blog posts that we've written have dealt with a single account. But what if you have an agency account and want to automate tasks or have other needs that require the use of the API? The chances are pretty good that you will want to perform these tasks for more than one, or even all of your subaccounts. With agency level API permissions, an agency user has the ability to login to the API and perform tasks in any subaccount just as though it was logged into the subaccount itself.

Let's Get Started

First, make sure you have an agency user with agency API access turned on. 

Note that this user does not need to have administrator privileges. This allows you to restrict the amount of access this user has in the Bronto web application, while still allowing access to the API.

Now you can login to the API using this username, password, and the sitename from from the Sign In tab of your agency preferences. As with logging into the agency portion of the Bronto web application, you can't perform subaccount activities just yet (i.e. updating contacts, sending messages, etc).  You'll first need to login to a specific subaccount by using the optional siteId parameter in the login function. This siteId can be retrieved by using the readAccounts function. In fact, this is the only function you'll have access to as an agency API user.  Once you have these siteIds, you may choose to store them locally. This way you won't have to go through the first step of logging in as the agency user and reading them.

Keep This In Mind...

If your subaccounts change somewhat frequently and you are creating an interface to allow someone in your organization to perform various subaccount activities, you may want to continue to perform the initial agency login and retrieval of siteIds step. Doing this allows you to present an up to date list of all your subaccounts.

Included is a PHP example that shows how you can use a single login function for both agency and subaccount logins. Let us know if you have any questions in the comments section below.

Alex Durzy
Support Engineer at Bronto