Agent-level API access to DeskPro using auth tokens

deskpro_agent_api_access.md

Agent-level API access to DeskPro using auth tokens

Intro

You can access DeskPro using a token that allows you to access the same API endpoints programatically as you could through the GUI. As a user, you can have a single API token for your account and expire or rotate it on demand. Like all keys, your token should be protected and kept secure, as it allows access to DeskPro under your user context without 2FA. As DeskPro has a public-facing endpoint, this could potentially be used to exfiltrate sensitive data. Both fortunately and frustratingly, API tokens are short-lived, making them suitable for infrequent script runs and not much else.

Getting your token

From the main DeskPro page, click your Profile icon in the upper-right and choose Preferences. Scroll to the bottom of that panel where there is a QR code. Scan it with a phone and you'll get a URL you can use to retrieve a user token blob. Open the link and you'll get a json file that looks like this:

{
    "data": {
        "person_id": 363442,
        "token": "857103:6X62QSZ4WGZ3X4Z8Y7KH697JBY",
        "discover": {
            "helpdesk_uuid": "a-super-real-uuid",
            "is_deskpro": true,
            "is_cloud": false,
            "helpdesk_url": "https:\/\/deskpro.mybiz.com\/",
            "base_api_url": "https:\/\/deskpro.mybiz.com\/api\/v2\/",
            "build": "1622578176",
            "build_id": 69514,
            "build_name": "2023.1.2",
            "apps_oauth_proxy_url": "https:\/\/deskpro.mybiz.com\/api\/v2\/apps\/proxy-oauth",
            "apps_http_proxy_url": "https:\/\/deskpro.mybiz.com\/api\/v2\/apps\/proxy-http"
        }
    },
    "meta": {},
    "linked": {}
}

We don't care about any of this other than the token field. Take note of it now. You'll need it in the next step.

Building your auth header

DeskPro is picky about the format of your requests. Since DeskPro only support HTTP Basic Auth, all your information goes into the header. Your headers must contain AT LEAST the following fields:

  Accept: application/json
  Authorization: token blah

The important component is the token portion of the Authorization value. This signals to DeskPro that you are authorizing as a user rather an application, which would instead use key.

Figuring out your API request

DeskPro provides API documentation at https://<deskpro_url>/api/v2/doc.

Putting it all together

A simple request using curl would look like this:

$ curl -X GET -H "Accept: application/json" -H "Authorization: token 857103:6X62QSZ4WGZ3X4Z8Y7KH697JBY" https://<deskpro_url>/api/v2/tickets/149571

{
    "data": {
        "id": 149571,
        "ref": "FKGE-4221-DAPH",
        "auth": "WGZ3X4Z8Y7KH697JBY",
        "parent": null,
        "language": null,
        "brand": 1,
        "department": 1,
        "category": 1,
        "priority": null,
        ...snip
    "meta": {},
    "linked": {}