Overview

In this document, we'll go over the basics on how to consume the Tasklist GraphQL API. Read more about how to build a real world application here.

Endpoint

Tasklist provides a GraphQL API at endpoint /graphql.

Authentication

To access the API endpoint, you need an access token.

Your client must send a header in each request:

Authorization: Bearer <Token>

For example, send a request using curl:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>" -d '{"query": "{tasks(query:{}){name}}"}' http://localhost:8080/graphql

How to obtain the access token

You must obtain a token to use the Tasklist API. When you create a Tasklist client, you get all the information needed to connect to Tasklist.

See our guide on building your own client.

The following settings are needed:

Name	Description	Default value
client id	Name of your registered client	-
client secret	Password for your registered client	-
audience	Permission name; if not given use default value	tasklist.camunda.io
authorization server url	Token issuer server	-

Send a token issue POST request to the authorization server with the following content:

{
  "client_id": "<client-id>",
  "client_secret": "<client-secret>",
  "audience": "<audience>",
  "grant_type": "client_credentials"
}

See the following example with curl:

curl -X POST --header 'content-type: application/json' --data '{"client_id": "<client-id>", "client_secret":"<client-secret>","audience":"<audience>","grant_type":"client_credentials"}' https://<authorization server url>

If the authorization is successful, the authorization server sends back the access token, when it expires, scope, and type:

{
  "access_token": "ey...",
  "scope": "...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Obtaining the Tasklist schema

To obtain the Tasklist GraphQL schema, send a request to the endpoint with a GraphQL introspection query as described here, or use the generated API documentation.

There are also several tools to explore GraphQL APIs.

For example, you want to know about provided types:

query {
  __schema {
    queryType {
      fields {
        name
        type {
          kind
          ofType {
            kind
            name
          }
        }
      }
    }
  }
}

Example requests and responses

Get all task names

Request:

{
  tasks(query: {}) {
    name
  }
}

Response:

{
  "data": {
    "tasks": [
      {
        "name": "Check payment"
      },
      {
        "name": "Register the passenger"
      }
    ]
  }
}

Get all tasks completed with id, name, and state

Request:

{
  tasks(query: { state: COMPLETED }) {
    id
    name
    taskState
  }
}

Response:

{
  "data": {
    "tasks": [
      {
        "id": "2251799813685728",
        "name": "Check payment",
        "taskState": "COMPLETED"
      }
    ]
  }
}