Creating API users in Responsys

Overview

The Responsys Account Administrator manages Responsys users. We recommend two dedicated API users for each account: one for production use, and one for QA use.

When creating an API user, the Account Admin sets the following two levels of user access in Responsys:

  • Organizational Access Control determines whether a user has access to a particular object in an organizational unit. When Organizational Access Control is enabled for a Responsys account, it will be enforced for all users in that account, including API users. This means that the API user's access to Responsys objects is limited by the organizational units to which the user is assigned. We recommend Root access for the API user, so that the API can access all objects for your account.
  • Functional Access Control determines what operations the user can perform with that object. The API user's access level to a specific object is determined by functional roles that are assigned to that user. For maximum API user access, we recommend the following roles:  Campaign Web Services Manager, Content Web Services Manager, Folder Web Services Manager, List Web Services Manager, and Table Web Services Manager.

Creating an API user

To create an API user:

  1. Log in to Responsys as a Responsys Account Administrator.
  2. From the Responsys home page, select Account from the sidebar.

Screenshot illustrating the procedure for accessing the Account Management page. Note that the navigation menu button described in the procedure is an unlabled graphic on the screen. Keyboard sequence: From the address bar, tab one time, press Enter key, press A key twice to select Accounts, and then press the Enter key.

The Account Management page is displayed.

Screenshot illustrating the procedure for accessing the Add User page

  1. From the Account Management page, locate the User Identity Management section and click Add User.

The Add a User to this Account page is displayed. The fields on this page may vary, depending on the features enabled for your account. The instructions that follow represent the most common configuration.

Screenshot illustrating the Add a User to this Account page described in this procedure

  1. Complete the following fields:
  • Login name: User’s login name
  • Email address: User’s email address. Set this email address to the point of contact for Responsys Web Services API development. Responsys sends the new user “welcome” email to this address, and the email recipient sets the API user password.
  • User display name: Name to display in the Responsys user interface. Although this is a required field, it is not relevant for the API user, because the API user will not have access to the Responsys user interface.
  • User Status: Leave this set to Active
  • User Locale: English by default.
  1. On the Role Assignment tab, select one or more of the following functional roles. This ensures that the user has access to all of the API calls in these object categories. For full standard API functionality, select all of the following. Do not select other roles for the API user.
  • Analytics Web Services Manager
  • Campaign Web Services Manager
  • Content Web Services Manager
  • Folder Web Services Manager
  • List Web Services Manager
  • Program Web Services Manager
  • Table Web Services Manager

NOTES:

  • Users assigned to only these functional roles do not have access to the Responsys user interface and are limited to using the Responsys API.
  • If you have been using Oracle Responsys since before August 2015, you are most likely using the older roles model known as legacy restrictions. The legacy restriction Cannot access UI (Web Service Access Only) is the legacy equivalent.

Screenshot illustrating the bullet describing legacy restrictions

  1. Click the Organization Assignment tab (if present), and then select Root. Objects created through the API inherit the organizational membership of the API user.

Screenshot showing Organization Assignment tab selected and the Root check box selected.

  1. Return to the top of the page, and then click the Create button.

Changing the API user password

After you create the user, Responsys sends a new user “welcome” email to the email address you entered when creating the API user, which should be your point of contact for Responsys Web Services API development. This email provides instructions for logging in to Responsys and for changing the password.

Notes:

  • The API user name is included in the greeting ("Dear username") and the login URL and temporary password are included in the message body.
  • Before using the API user, the person who received the email must log in and change the temporary password to the one that Responsys expects if you use the username and password API authentication method.
  • The API user, if configured purely as such, will not have access to the Responsys user interface. Attempting to log in by using the Responsys user login results in the following error message: ui.authentication.login.browserLoginNotAllowed

Troubleshooting API user password reset issues

In Responsys, API users do not have access to the Responsys user interface. Usually this does not affect the API user setting the password: the new user receives the email and is prompted to create a new password, the new user clicks the link in the email, and then the new user is able to enter the new password. However, sometimes the person configuring a new API user receives a ui.authentication.login.browserLoginNotAllowed error when they try to reset the temporary password.

If this occurs, the workaround is to ask the Responsys Account Administrator (or any Responsys user with the Account Administrator role assigned) to log in to Responsys and reset the API user's password.

To reset the API user password:

  1. Log in to Responsys as a Responsys Account Administrator.
  2. From the Responsys home page, click the navigation menu button, and then select Account.
  3. Locate the User Management section, and then click Manage Users.
  4. Locate the API user's display name in the list, and then select it.
  5. Click Reset Password. An email is sent to the user that will enable the user to reset the password without logging in to Responsys. Client applications that authenticate as the API user must use the new password.

Testing the API user

You can use Postman to test the API user. Try the REST API for username and password authentication. If these succeed and the system returns the authentication token, then the API user is ready for your client application to use.

[API user, create user, username, password, reset password]

Learn more

Authentication