Deskpro Developer Starter
  • Introduction
    • Introduction
  • Embeddables
    • Website Widget
    • Form Embed
  • API Basics
    • API Introduction
    • Auth
      • API Keys
      • API Tokens
        • OAuth
        • Token Exchange Endpoint
      • Access Control
    • API Reference
    • Request Format
    • Batch Requests
    • Sideloading
    • SDKs
  • Getting Started with the API
    • PHP
      • Initialize the client
      • Add a form
      • Create an article
      • Tickets
      • Methods
    • JavaScript
      • Initialize the client
      • Add a form
      • Create an article
      • Methods
Powered by GitBook
On this page
  • Endpoint Tags
  • Access Modes
  1. API Basics
  2. Auth

Access Control

PreviousToken Exchange EndpointNextAPI Reference

Last updated 3 years ago

Endpoint Tags

Every API endpoint in the system has one or more "tags" associated with it.

You can view the tags for a particular endpoint by finding it in the . Expand the API endpoint to view the details, and under the "API tags for this endpoint" heading will be the list of tags applied to the endpoint.

The tags assigned to any given API endpoint usually follow a pretty standard pattern with a tag being composed of keywords from least specific to most specific.

  • There's a top-level grouping. For example, tickets. means the tag is applying to something to do with tickets.

  • A resource or object grouping. For example, tickets.tickets. means the tag is applying to an actual ticket (opposed to, say, a custom ticket field).

  • An operation like tickets.tickets.list means to get a list of tickets.

    • The common operations are: list, get, post, put, and delete.

For example, GET /api/v2/tickets has a tag of tickets.tickets.list. And DELETE /api/v2/tickets/{id} has a tag of tickets.tickets.delete.

You can fine-tune access to API endpoints by specifying a tag pattern when you define the API key in Admin > Apps > API Keys. In the "Tags" tab, enter one or more tags you want to allow access to.

You can use wildcards to whitelist a whole group of related tags (indeed, the default value for API keys is to allow all API endpoints so the value is *). You can also use a minus symbol to remove specific actions you don't want to allow.

Examples:

  • * all API endpoints

  • *, -tickets.* all API endpoints except tickets

  • tickets.*, -*.delete all ticket endpoints but nothing to do with deleting

  • tickets.tickets.list only allow using the ticket listing API

Access Modes

Most of the time, most APIs are available to any authenticated user of the API. But some APIs are locked down so they cannot be used except by users accessing the API by a specific method.

  • key is the most common and means the API can be used via an API key

  • token means the API can be used by a token

  • session means that the API can be used from the browser if the agent/admin is currently logged in. These are typically APIs used by the agent or admin interface in Deskpro itself.

You almost never need to worry about this. Typically only internal APIs are marked as session or token only.

You can view these limitations on each endpoint by viewing the . In an expanded node for an endpoint, notice the value for "Applicable API Modes".

Full API Browser
Full API Browser