Adding or editing an API user

SECURITY  Security level with Admin permission to configure Resources/Users (HR). Refer to Admin security settings.

NAVIGATION   > Admin > Extensions & Integrations > Other Extensions & Tools > Integration Center > select an integration vendor > context menu > Add API User

NAVIGATION   > Admin > Organization Settings & Users > Resources/Users (HR) > Resources/Users (HR) > Resources/Users > New > New API User

The external integrations listed on the Integration Center page require an API user account to communicate securely with the application. We recommend creating a unique API user account for each integration so that you can easily trace lockout issues and monitor application activity.

An API user is a special type of account required for communication with the Autotask API. These accounts are free of charge, but they do not provide access to the Autotask UI. API users cannot be assigned as a resource to content such as opportunities or tickets, but they can be selected as a filter on fields and in widgets that are date, time, or audit stamps.

EXAMPLE  System audit fields that are named Created By or Last Activity By include API users in their filtering options.

It is a best practice is to set up a separate API user account, and maybe even a separate API User (system) (API-only) or API User (system) Can't Read Costs (API-only) security level, for each integration with which your developers are working. Doing so enables you to tailor the security permissions to the areas required by each integration.

For partner integrations that appear on the Integration Center page, you can add API users right from the page. Refer to Integration Center.

There are two similar but different default system security levels available for API user accounts. Before you create your API User, it's important to understand the level of access your resources and integration partners will receive with each.

API User (system) (API-only): Use this system security level for resources and integration partners who will work with integrations via the API and do not need to access Autotask via the UI. The API User (system) security level grants full access to all Autotask data, including internal costs, for the roles to which it belongs.

API User (system) Can't Read Costs (API-only): If you need to grant API User access to an integration partner, but you prefer that they not have the ability to view your internal cost data, select this security level. The API User (system) Can’t Read Costs role has access to all data for the roles to which it belongs, but calls to Query will return no data for cost fields. The API will also ignore calls to Update for cost fields.

IMPORTANT  An API user is forbidden from creating resources (users). It is also prohibited from modifying its own security settings or updating multifactor authentication (MFA) configurations.

Creating an API user

SHOW ME  Want to learn how to set up this feature? Log in to Autotask and begin the walk-through. (Feature access required)

To create an API user account, do the following:

  1. To open the page, use the path(s) in the Security and navigation section above.
  2. Populate or edit the following fields:
Field Description

First/Last Name

First Name, Middle Name, and Last Name are referenced in many other entities, usually in combination with a role the person is playing in this context or an action they are taking.

Enter the individual's first (given) name, last name (surname), and, optionally, middle name.

Email Address

 This email address will be used for notifications should there be a problem with the integration. Enter the email address of a person who will be able to take action if an error occurs.

Active

This value defaults to true.

Locked

If an API user has been locked out because of repeated unsuccessful log in attempts and that resource cannot unlock the account from the log in page, clear the check box to unlock the account.
The number of unsuccessful consecutive user attempts before the user account is locked is determined by a system setting. Refer to System settings for site setup.

Security Level

The Security Level list only includes active API-only security levels (in ascending alphabetical order) plus the currently assigned level, if that is now inactive. Select an API security level.

Date Format

The date format defaults to the default location’s date format. The drop-down selector contains all of the available date formats.

Time Format

The time format defaults to the default location’s time format. The drop-down selector contains all of the available time formats.

Number Format

The number format defaults to the default location’s number format. The drop-down selector contains all of the available number formats.

Primary Internal Location

The primary internal location determines the timezone associated with the API user.
Field Description

Generate Key

Click this button to auto-generate a 15-digit username (key).

The Username (Key) field will be populated.

Username (Key)

This field is auto-populated when the Generate Key button above the field is clicked.

You can override the auto-generated username if you meet the following requirements:

  • Must contain letters and numbers
  • May contain special characters (but the following special characters are not allowed: @ ( ) ; : [ ] | \ ")
  • Must be unique for your Autotask instance (including inactive resources)

Generate Secret

Click this button to auto-generate a 25-digit password (secret).

The Password (Secret) field will be populated.

Password (Secret)

This field is auto-populated when the Generate Secret button above the field is clicked. The password will match the Password requirements configured in the system settings for Site Setup. If your target application does not allow 25-character passwords, you can shorten or override the auto-generated password.

In Edit mode, the password is not displayed. If you need to see the password, you will need to click Generate Secret to generate or input a new password.

Beginning with SOAP API version 1.6 and all versions of the REST API, all calls except getZoneInfo() require a tracking ID that identifies the API user and, therefore, the integration vendor that generated the call. The tracking identifier enables us to selectively disable integrations and vendors that are causing problems, without impacting API access for everyone else.

A radio button presents the following options:

Radio Button Option Description

Radio buttons
Integration Vendor This is the default option. You must use it if your vendor has created an integration with Autotask that is listed in on this page: Integration Center.
Custom (Internal Integration) Select this option if you have created your own custom integration with Autotask using our API. A tracking ID is auto-generated, and the Internal Integration Name field appears and is required.

Enter a unique name for your internal integration. You can use this tracking ID to access version 1.6+ of the SOAP API and all versions of the REST API for your company's Autotask instance only.

Once the API user is saved, the tracking identifier cannot be changed.

IMPORTANT  Existing vendor integrations will not work with a custom tracking identifier. You must use the vendor ID in the Integration Center. If your vendor is not listed, contact the vendor.

Additional Fields
Integration Vendor (only if the Integration Vendor radio button is selected) If you are creating an API user from the context menu of an integration vendor on the Integration Center page, that vendor will be selected in the Integration Vendorfield. The radio buttons and drop-down control will be disabled.

If you create the API user from the Resources page, click the drop-down control in the Integration Vendor field and select your vendor.
Application (only appears if the selected Integration Vendor is a middleware vendor offering multiple integrations Enter the name of the middleware application.
Internal Integration Name (only if the Custom (Internal Integration) radio button is selected) Enter a name for your custom integration with Autotask.
Tracking Identifier (only if the Custom (Internal Integration) radio button is selected) This is the tracking identifier that will authenticate API calls from this user account to Autotask. It must be copied into the SOAP header. Refer to The API tracking identifier.

All available Division > Line of Business pairings are listed in the Not Associated pane. You can associate an API user with a line of business, but be aware that any errors will not be visible to the user. Unless your business is strictly segregated by line of business, we advise against LOB associations.

EXAMPLE  If an API user is not assigned to the line of business that billing items on an invoice are assigned to, then the invoice will not be transferred to QuickBooks.

To associate the API user with one or more lines of business, do the following:

  1. Select one or multiple Division > Line of Business pairings and click the right arrow. The pairings will move to the Associated tab. As needed, click the left arrow to remove a pairing.
  2. To allow the API user to view such items, select Resource can view items with no assigned Line of Business.
  3. Click Save & Close.

Refer to Associate a user with a line of business on the Resource page.

  1. Click Save & Close.
  2. Update your integration with the new API user's credentials. The application should now be able to authenticate into Autotask.