Tutorial: Tokens Authentication for API Integration

Document created by Brendan Cooper Administrator on Jun 19, 2017Last modified by Brendan Cooper Administrator on Jun 20, 2017
Version 7Show Document
  • View in full screen mode

Samanage has released Encrypted Token Authentication which provides enhanced security while utilizing our API. This feature allows Samanage Administrators to generate a token via the Samanage application that encrypts your credentials and increases security across the organization. Once generated, the token can only be viewed by the user that created the Token and will allow them to regenerate the token using the same UI.  Here are the essential details on this feature:


Before You Start:


  • This will not impact current Username/Password API Authentication:  This feature will not impact those currently using Username/Password authentication, however, for security reason, Token Generation is highly recommended, as Username/Password authentication requires heavier maintenance depending on your password reset policy.  We suggest planning a transition process to update your current API connections, moving to the Token format.
  • Token Authentication replaces HTTP Digest Authentication:  Again, for security reasons, we have ended support on HTTP Digest Authentication, and replaced with Token Authentication.  Please see our previous post on HTTP Digest for more details.
  • API Documentation:  Please visit our API Documentation page for further details on utilizing our API.
  • Where to use Tokens: Using Token Authentication will bring added security to both your API Scripts and the Samanage Applications Integrations feature (more details below).


How to Setup Token Authentication:


Important Details for Setup:

  • You must be a System Administrator to setup Token Authentication.
  • Token issued by a user have same permissions as that user’s role, if the user’s permissions change after token is issued, so does the token's permissions.  We recommend tokens should only be associated to Administrators with full application access.  
  • You can ONLY create and view Token’s associated to yourself, thus you cannot generate Tokens of others, or reference other User’s Tokens.
  • If a Token is Reset or Deleted, this will break the API connection that the specific Token is associated to, and the Script/Application Integration associated will need to be fixed.
  • If you disable the User who generated the Token, the Token will also be disabled.


How to Setup:

1. Go to the Setup options and click on the “Users” page

2. Search for yourself, and click your Name to go to your User Detail page (not your User Profile Card) 


3. Click the “Action” dropdown, and select “Generate JSON Web Token”


4. You will now see your Token, along with some options:

  • Copy: Copies the Token to your Clipboard
  • Reset: Resets your Token
  • Delete: Deletes your Token
  • Hide Token: Minimizes your Token, and replaces with a “Show Token” link



5. Copy the Token, and utilize it in one of the following ways:


  • Using Tokens for API Scripts


    • See the below example on how to insert the Token for authentication in your scripts.


Example for CURL:


curl -H "X-Samanage-Authorization: Bearer ZWV0YXkubmF0YW4rNUBzYW1hbmFnZS5jb20hbGciOiJIUzUxMiJ9.eyJ1c2VyX2lkIjoxMjU2OTQzLCJnZW5lcmF0ZWRfYXQiOiIyMDE3LTA2LTA3I


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



    • Go to the Setup Option for Applications Integration
    • Add a new, or edit an existing integration, and modify the Authentication Method to “Samanage Web Token”



We hope that this tutorial is helpful.  As you begin to use Tokens Authentication for your API integrations, we ask that you share examples of how this feature has benefited your organization. The wisdom of the community is an extremely valuable way for our users to learn how to use the latest features.  So, please share examples and ask questions of each other - we look forward to hearing from you.


Your Samanage Team

6 people found this helpful