Admin Guide

Using the Deskpro API


Deskpro has a full REST API allowing access to the functions of the helpdesk using HTTP requests.

The API enables you or your developers to have your external code retrieve, modify or create helpdesk data, such as tickets, users and so on.

See the Developer Manual for full details.

You can explore the Deskpro API and quickly try out the available operations using our API browser. This gives you a web interface to interactively enter API requests and see the results, so you can test how the API works.

Go to yourhelpdesk/api/api.html to see the API browser. You will need to generate and enter an API: Managing API keys to use the browser.

Managing API keys

For external code to access the Deskpro API, it will need to use a Deskpro API key.

Warning

Anyone with access to one of your API keys can change and delete data in your helpdesk, so you should be very careful about sharing or publishing them.

When you create an API key, you must select what privilege level it has:

  • Superuser Key: can act as any agent, as specified in the API request - optionally, you can choose a default agent that will be used if no agent is specified. You can optionally give a superuser key access to use admin functions like listing other keys.
  • Normal Key: API requests are treated as if they were performed by a specific agent.

If you enter a superuser key in the API browser, note that operations will always be carried out as the default agent; if you don’t set a default agent for the key, it won’t work in the API browser.

If it’s not important for the app to be able to act on behalf of your human agents, you may want to create a dedicated agent account for it.

../_images/api-key-settings.png

To generate a key:

  1. Go to Apps > API Keys.
  2. Click + New API Key.
  3. Enter a brief Description which explains what the key will be used for.
  4. Set if you want the API key to be a Superuser key or a Specific Agent key.
  5. Click Save. Click on the key in the list at the left to view the API key.

The number at the front of the key code, before the :, is the ID number of the key.

You should make a separate key for each external service/app that will be accessing your helpdesk through the API.

Note

You can test which API key has been used in the criteria for a trigger or other automated action.

To help with app development and monitoring API usage, you can see a log of the last 50 API requests in the API Key Logs tab.

If you think a key has become known to somebody you don’t trust, you can Delete or Regenerate it. Regenerating a key means its description is kept, but the key code is changed and the old one will no longer work.

../_images/api-key-existing.png

Comments (0)

Add a comment

Add a comment

You need to log in before you can submit a comment.

Need a password reminder?