Defining an API User
License Type Requirement
In the past, API permissions were added to regular user accounts you used to log into the UI, and cost the same as any other license. Starting with SOAP API version 1.6 and all versions of the REST API, working with the Autotask Web Services API requires a special license type, which is free of charge.
The API User (system) license type does not permit the user to log into the Autotask UI. Autotask provides a system security level with this license type that can be copied, tailored to your requirements, and assigned to API users. You can create up to 50 custom API security levels, and assign them to an unlimited number of API users. Refer to API User (system).
The default API User (API-only) security level provides the same API access as the standard Full Access security level. It cannot be edited, but it can be copied. You can edit the copies to create up to 50 API-only custom security levels that provide access to modules, features, and data as needed, in the same way that regular Autotask security levels control access to features and data.
- API-only resources cannot log into the Autotask UI.
- They cannot be assigned to tickets or tasks; their names do not appear in any resource data selectors or resource menus.
- API-only resources can create entities (via the API) but they cannot own or be associated with them.
An API User can be a CreatorResourceID, but cannot be a ResourceID or OwnerResourceID (except in select cases where Autotask does not distinguish between a CreatorResourceID and a ResourceID; that is, the entity does not have an explicit CreatorResourceID but does have another ResourceID).
- You can exempt API-only users from the password expiration requirement.
When you make a copy of the API User (system) (API-only) security level, you can check the "Not required to change password" check box. Refer to Create or edit a custom security level.
API-only resources must be created and managed through the UI. You assign an API-only security level to a resource on the Security tab of the Manage Resource page in Autotask. Refer to Complete the Security tab.
NOTE Access to protected Asset UDFs, which may store sensitive data, is not granted by default. Access is granted separately by resource. Refer to Manage permission to view protected data.
NOTE Autotask Web Services API does not currently support single sign on (SSO). If you are using SSO with Autotask, the API will recognize your Autotask credentials used prior to SSO. The password will not expire.
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) - 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 - 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.
For more details about API User access privileges, review our System security levels article. To learn how to manage your API Users, refer to Adding or editing an API user.
How to...
IMPORTANT If you integrate Autotask with multiple applications, you must create a separate API user account for each integration. We encourage you to also create a specific security level for each integration, and disable access to features that are not required for the specific integration.
EXAMPLE Your lead processing integration does not require access to billing features. It will enhance security if the API user account of the integration developer does not have access to them.
All Autotask databases contain a system security level called API User (system) (API-only). A user with an HR Admin security level must log into Autotask and do the following:
- Make a copy of the API User (system) (API-only) security level. The system security level cannot be modified, but copies of it can be edited to match your integration requirements. You can make up to 50 API-only security levels.
NOTE You can also use the system security level as-is. Refer to System security levels.
- Create a resource and assign an API User security level. Refer to Complete the Security tab.
If you are using an existing vendor integration...
If you are going to make use of an existing vendor integration, most of the work is already done for you.
- Navigate to > Admin > Extensions & Integrations > Other Extensions & Tools > Integration Center.
- Check if your vendor is listed.
- If yes, activate the integration for your database.
- Then, create an associated user account for your integration developer and select an API User security level.
For more details, refer to The Integration Center.
If your vendor / application is not listed or you are integrating with a custom application...
- Copy and tailor the API User (system) security level to your requirements.
- Create a resource and assign an API User security level. Refer to Complete the Security tab.
Each API user has a tracking identifier (Integration Code, Vendor Tracking ID) that allows them to integrate with one application only, either a vendor application or a custom application. Unless they also have a login to the UI with an HR Admin security level, they will not be able to discover the tracking identifier they are supposed to use, so you must communicate the 27-character ID to the developer.
The developer must then insert the tracking identifier into the SOAP header inside the IntegrationCode tags with each query as shown below.
IMPORTANT They must also add the xmlns="http://autotask.net/ATWS/v1_6/" tag, or the integration won't work properly.
For details on assigning API tracking identifiers, refer to API tracking identifier.