Skip to main content
Version: latest

Overview

In this article we'll go over the basics you need to know on how to consume the Tasklist GraphQL API. To read more about on how to build a real world application you can click 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:

NameDescriptionDefault value
client idName of your registered client-
client secretPassword for your registered client-
audiencePermission name, if not given use default valuetasklist.camunda.io
authorization server urlToken issuer server-

You 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 here.

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 tasks 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"      }    ]  }}