DeskDirector API

DeskDirector API

DeskDirector provides a set of generic and platform APIs for you to integrate with. With this, you can trigger workflows based on Webhooks (such as ticket status changes), add ticket notes on behalf of a user, or modify permissions through the admin API.

In this article, we will go through what is available and the authorisation system.

Exploring the APIs

Every DeskDirector instance has a Swagger interface that allows you to explore our API. To see this, navigate to https://[your-subdomain-here].deskdirector.com/swagger. At the top of the Swagger interface, you can select which API version you would like to reference.

API Versions

• API v4: This is the newest version of our API and is under active development
• API v3: This version of our API was made available when we moved from the legacy Admin Console to the new Admin Portal
• API v2: This is the API you will see used for most actions in DeskDirector. It is a solid and well-supported API and is used by all our existing systems. For most users, this is what we recommend you use in your automations.
  API v2 uses camelCase for JSON response keys.
• API v1: This API has been deprecated and is only used by our legacy systems. We do not recommend using this version, and we do not provide any support for it.
  API v1 uses PascalCase for JSON response keys.

Categories

• Public API: In general, this API is only used for retrieving information about your DeskDirector instance or querying certain entities inside DeskDirector.
• Admin API: These API's are used for our Admin Portal. We have recently allowed API keys to used against admin-related API endpoints. API Key's role is equivalent to an admin role.
• Portal API: These API's are used by the Portal.
• TECH API: These API's are used by TECH.

Requirements

You will need access to two things to use the DeskDirector API:

1. An API key. You can find this under Admin Portal > Advanced > API Keys (or Admin Portal > Advanced > Developer Corner if using a PSA backend): This is needed if you are trying to access the API programmatically, as you'll need to generate an access token. If you only need a one-off check, you can skip this.
2. An Access Token: This is used to authenticate to most DeskDirector API endpoints.

Generating an Access Token Programatically (Tokity Only)

To generate an access token, you need to send the following request to the API endpoint for the client you are trying to generate the token for.

GET /api/v2/user/member/<member id>/userkey?expiresIn=<expiry time in minutes> HTTP/1.1
Host: https://<Your DD Instance Name>.deskdirector.com
User-Agent: <user agent>
Accept: */*
Authorization: Basic <API Key>

This will respond with a user key that you can use as your access token:

{
    "userKey": "<access token>",
    "expires_in": <expiry time in seconds>,
    "expires_on": <expiry time stamp>
}

Generating an Access Token Programatically (ConnectWise/Autotask Only)

To generate an access token, you need to send the following request to the API endpoint for the client you are trying to generate the token for.

GET /api/v2/user/member/<member id>/userkey?expiresIn=<expiry time in minutes> HTTP/1.1
Host: https://<Your DD Instance Name>.deskdirector.com
User-Agent: <user agent>
Accept: */*
Authorization: DdApi <API Key>

This will respond with a user key that you can use as your access token:

{
    "userKey": "<access token>",
    "expires_in": <expiry time in seconds>,
    "expires_on": <expiry time stamp>
}

Generating an Access Token Manually

Under Admin Portal > Advanced > Developer Corner, Click on "Generate Access Token". This will generate an access token that lasts for one hour.

Consuming DeskDirector API

Once you have an Access Token, you can send requests to the DeskDirector API as you normally would. Please note that the DeskDirector API can be quite inconsistent due to how it is used internally and due to rapid development schedules at DeskDirector.To generate an access token, you need to send the following request to the API endpoint for the client you are trying to generate the token for.

GET /api2/admin/stats/sync/errors HTTP/1.1
Host: https://<Your DD Instance Name>.deskdirector.com
User-Agent: <user agent>
Accept: */*
Authorization: DdAccessToken <access token>

When authenticating directly to the DeskDirector API without authenticating as a user, you would use:

• Authorization: Basic <API Key>: used for Tokity partners.
• Authorization: DdApi <API Key>: used for ConnectWise/Autotask partners.

Generating API Keys

Tokity Partners

1. Head to the Admin Portal and open the Advanced > API Keys tab
2. Click on Create API Key:

   

3. Fill out the details and allowed permissions for your API Key:

   

4. Click Create API Key
5. Note down the details returned for your API key:

   Basic Authentication
   Username: global
   Password: 3RSM9s3Qwve2eC-1lvcQm6LHVjtFPljtxpQmjP3WG46W21FjQnUNZ7wTRryr4B0UD5Vp7D4Ai8waL9d9k00
   
   Authorization Header
   Authorization: Basic Z2xvYmFsOjNSU005czNRd3ZlMmVDLTFsdmNRbTZMSFZqdEZQbGp0eHBRbWpQM1dHNDZXMjFGalFuVU5aN3dUUnJ5cjRCMFVENVZwN0Q0QWk4d2FMOWQ5azAw
   
   Power Automate Connector or Azure Copilot
   Site Host: <Your MSP Name>.deskdirector.com,
   API Key: Z2xvYmFsOjNSU005czNRd3ZlMmVDLTFsdmNRbTZMSFZqdEZQbGp0eHBRbWpQM1dHNDZXMjFGalFuVU5aN3dUUnJ5cjRCMFVENVZwN0Q0QWk4d2FMOWQ5azAw

ConnectWise/Autotask Partners

1. Head to the Admin Portal and open Advanced > Developer Corner
2. Click on Regenerate to generate/regenerate your API key:

   

3. You can then view and copy your API key for use with Power Automate, Teams, and for programmatic access

Basic vs Authorization Header (Raw/API) Auth

When using basic authorisation, your requests sent on behalf of an API member (rather than a contact/agent) will use a username and password.

In your rest client, you will typically see these as Username and Password:

Username: global
Password: 3RSM9s3Qwve2eC-1lvcQm6LHVjtFPljtXpQmjP3WG46W21FjQnUNZ7wTRryr4B0UD5Vp7D4Ai8waL9d9k00

When using the authorisation header, you will instead have a single header value on your request with the key Authorization and the value Basic <Your Base64 Encoded Username:Password here>:

Authorization: Basic Z2xvYmFsOjNSU005czNRd3ZlMmVDLTFsdmNRbTZMSFZqdEZQbGp0eHBRbWpQM1dHNDZXMjFgalFuVU5aN3dUUnJ5cjRCMFVENVZwN0Q0QWk4d2FMOWQ5azAw

DD API with Bruno & Postman

The DeskDirector API can be easily imported into Postman or Bruno so you can explore it with ease.

Importing into Postman

1. Open your DeskDirector API Swagger instance and navigate to the API version you're wanting to use:

   

2. Copy the OpenAPI spec link:

   

3. In Postman, select Import:

   

4. Paste the URL for your API spec and then select Postman Collection:

   

5. Under View Import Settings, select whether you want it to display your API based on tag (folder nesting will appear as it does in Swagger) or based on path (folder nesting will be based on the API endpoint's path):

   

Importing into Bruno

The process for Bruno is much the same as Postman, except that you'll either import as a .bru collection or as a an Open Collection.