The most common way to use the API is with an API Key.

An API Key can be defined from within Deskpro at Admin -> Apps -> API Keys. You can define as many API keys as you want.

Performing API calls with an API key

Here’s an example call made to the helpdesk/discover endpoint:

curl -H "Authorization: key 2:YWK2PGCS8CNW62SR8TBTBKWMY" \
    http://example.com/api/v2/me
 copy

{
    "data": {
        "auth_method": "api_key",
        "app_id": null,
        "person_id": 1,
        "person": {
            "id": 1,
            "...": "..."
        }
    },
    "meta": {},
    "linked": {}
}
 copy

Options

API Key Code

The Key Code is like a password. You use this in your API requests to authenticate the request.

API Key Context

Sets the user context for requests using this key, which dictates what actions the key can actually perform. For example, if you set the agent to "Matthew", it means any API request you make with this API key will be run with all the permissions that Matthew normally has.

Machine Key

A Machine Key is an API key that can be bound to any agent. This makes it possible to specify the agent context at the time you make the API request rather than at the time you make the API key itself. This gives you some flexibility, but also makes the API key rather sensitive because it can potentially be used to do a lot more things.

When using a Machine Key, you specify the agent ID context in a special header called "X-DeskPRO-Agent-ID". E.g.

curl -H "Authorization: key 2:YWK2PGCS8CNW62SR8TBTBKWMY" \
    -H "X-DeskPRO-Agent-ID: 4" \
    http://example.com/api/v2/me
 copy

Allow / Disallow Tags

All API endpoints are tagged (see the API reference for tags). You must specify which tags your API key is allowed to use, and you may optionally disallow specific tags here too. You can use asterisks as wildcards.

The most permissivie API key would be one with an allow tag of * which would match everything.

See here for more information: Access Control with Tags

FAQ

So the things I can do with the API depends on which agent the key is bound to?

That's right. The API key inherits all permissions from the agent it's bound to. For example, if an agent can't access tickets assigned to other agents, then using the API to do that will fail as well.

How do I create a "super" API key that can do anything?

This is typically done by creating an API key bound to an administrator user who has permissions to do everything.

Can I lock-down an API key so it can only do specific things?

Yes, this is done by allowing specific tags. See the "Allow / Disallow Tags" section above.