Using the API

Everything you can do in the Mabato web application, other programs can do through the API: a script that reads your tasks, a tool that creates tasks from another system, or a chat bot. A program signs in with a personal API token that you create yourself. It acts as you, so it sees exactly the projects you can see and may change exactly what you may change.

You do not need the API for everyday work. This chapter is for people who connect Mabato to other tools.

API tokens

Create a token

Select API tokens in the top bar. On a phone, open the menu (the Mabato button with the three-line icon) first.
Under Token name, type a name that tells you what the token is for, for example Reporting script.
Select Create token.
Copy the token right away: select Copy to clipboard and paste it into the tool or a password manager. Mabato says Copy this token now — it won't be shown again.
Select Done. The token value disappears from the page.

The API tokens page right after creating the token Reporting script: the one-time notice, the token value with the Copy to clipboard and Done buttons, and the token in the list — The API tokens page right after creating a token. The new token value is shown once, above the list.

Every token in the list shows its name, when it was created, and when it was last used (or Never used). The list never shows the token value itself, not even to you. If you lose a token, revoke it and create a new one.

The API tokens page after leaving it and coming back: the token Reporting script is listed with its creation time and Never used, with a Revoke button, and the token value is gone for good — The list of tokens after reopening the page, with one token and its Revoke button.

Revoke a token

Select API tokens in the top bar.
Select Revoke next to the token. The token is revoked at once, without a confirmation, and cannot be restored.

The API tokens page after revoking the token: the list is empty again and says No API tokens yet. — The API tokens page after the last token was revoked.

A program that still uses a revoked token gets the answer 401 from then on.

Calling the API with a token

Send the token in the Authorization header of every request, after the word Bearer. The API lives under the address of the application with /api/v1 added. In the examples, replace <your-mabato-host> with the address you open Mabato at, and <your-token> with your token.

List the projects you can see:

curl -H "Authorization: Bearer <your-token>" \
  "https://<your-mabato-host>/api/v1/projects"

List your unread notifications:

curl -H "Authorization: Bearer <your-token>" \
  "https://<your-mabato-host>/api/v1/notifications?unreadOnly=true"

The answers are JSON. To keep the token out of your shell history, store it in an environment variable first, for example export MABATO_TOKEN=..., and write "Authorization: Bearer $MABATO_TOKEN" in the command.

Answers that mean something

Status	Meaning
`401`	The token is missing, mistyped, or revoked. Check the header and the token list.
`403`	The token is fine, but you are not allowed to do this, for example changing a project you can only view.
`404`	The thing does not exist, or you may not see it.
`409`	The project is closed, so it cannot be changed.

The API reference

The API reference lists every operation of the API with its parameters and answers, and lets you try operations in your browser. It is a separate page, not part of the application you work in. You find it at the developer address of your installation. That is the address you open Mabato at, with dev. in front: if Mabato is at <your-mabato-host>, the reference is at dev.<your-mabato-host>. If you are not sure, ask your administrator for the address of the API reference.

Open the API reference in your browser. It works without signing in.
Select Authorize, paste your API token into the field of the dialog and select Authorize there, then close the dialog. The reference offers only the token, because it cannot use your browser session.
Open an operation, for example the one that lists projects, and select Try it out, then Execute. The page shows the request that was sent and the answer.

The reference does not store your token. Close the page or reload it and you must authorize again.