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:
- To open the page, use the path(s) in the Security and navigation section above.
- 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. |
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:
|
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:
- 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.
- To allow the API user to view such items, select Resource can view items with no assigned Line of Business.
- Click Save & Close.
Refer to Associate a user with a line of business on the Resource page.
- Click Save & Close.
- Update your integration with the new API user's credentials. The application should now be able to authenticate into Autotask.