Documentation forService Desk

Token authentication for API integration

On this page

Introduction

As an administrator, it is imperative that you maintain the highest level of security within your organization while simultaneously allowing the most efficient process integration to be enabled. To allow for this balance, Service Desk provides token-based authentication that encrypts your credentials and enhances security across the organization while enabling the use of APIs.

Tokens can only be viewed by the user (administrator) who created the token. You (creator) can also regenerate the token using the same UI.

Factors for all customers to consider

  • Only someone with a Service Desk administrator license can generate an API token.

  • SolarWinds recommends tokens should be associated only by administrators with full application access. Any issued token shares the same permissions as the specific user’s role; when user permissions change after a token is issued, the token's permissions also change.

  • If a token is reset or deleted, the API connection associated with the specific token is broken, and the associated script/process integration will need to be corrected.

  • Users can ONLY create and view tokens associated to themselves. No one can generate tokens for others, or reference other users' tokens.

  • If the user who generated the token is disabled, the token is also disabled.

  • There is no impact on current username/password API authentication. This feature does not impact users currently utilizing username/password authentication. However, for security reasons, token generation is highly recommended, as Username/password authentication requires heavier maintenance depending on your organization's password reset policy. SolarWinds suggests planning a transition process to update your current API connections if necessary, moving to the token format.

  • Using token-based authentication enhances security to both your API scripts and the process integrations feature.

  • API documentation is available at the API Documentation site).

Additional API factors for ESM customers to consider

  • API requests are authenticated using tokens, which contain information about both the ESM service provider and the user. As a result, API calls should be directed to api.samanage.com. Following the migration to ESM, if customers continue to use APIs with tokens, all API functionalities will persist, as each service provider has its unique URL for browsing purposes. This ensures that the system can identify the relevant service provider when the user is authenticated using Single Sign-On (SSO) or user/password.

  • Tokens for the IT Service Provider (formerly your ITSM account) are retained. However, admininstrators must generate a new token for each service provider, including for the Organization level and use the specific token for the corresponding service provider/organization API call.

  • Administrators can generate a token directly from the User setup page. The token is needed by the API developer to gain access to specific items in Service Desk accessible only via the API. When an administrator re-generates their token (via the User setup page), all previously generated tokens become invalid.

Set up token authentication

Only administrators in Service Desk can generate tokens. JSON web tokens will not break if the user's email address is changed or the user's password is reset.
  1. Navigate to Setup > Users & Groups > Users and locate your User detail page (not your User Profile Card). You can also use the search bar to go directly to your user and click on your name for details.
  2. From the user detail page, click Actions and select Generate JSON Web Token from the dropdown menu. (Service Desk administrator rights required.)
  3. In the user detail page under JSON Web Token you can see the following options:
    • Copy. Copy the token to your clipboard.
    • Reset. Reset your token.
    • Delete. Delete your Token.
    • Hide Token. Minimize your token, and replaces with a Show Token link.
  4. Click Copy.

Use the token for API scripting

The example below displays how to insert your Token for authentication in API Scripting:

Example for CURL:

-H 'Accept: application/vnd.samanage.v1.1+json' -H 'Content-Type: application/json' -X GET https://api.samanage.com/incidents.json

For information on where to add the token in the CURL command, see Service Desk API.

Use the token for Process integration

  • Navigate to Setup > Integrations > Process Integrations.

  • Add a new, or edit an existing integration, and modify the Authentication Method to Service Desk Web Token.