Skip to main content
Version: next

JATOS API

Introduction​

Since version 3.8.1 JATOS offers an (HTTP) API to make integrating JATOS into other tools easier. One usecase is to call JATOS directly from Python, R, Matlab (or any other programming language).

Things that are possible with the API:

  • Import/export studies
  • Update your study by uploading/downloading/deleting single study assets files
  • Export results
  • Export study/componnent properties
  • Get study codes (to run studies)

Have a look and try it out​

  1. You can use petstore.swagger.io to see all endpoints including their descriptions and even try it out with your local JATOS (by clicking the link the API specs will be automatically loaded)
  2. To test the API with your local JATOS choose the server http://localhost:9000 (probably already set)
  3. JATOS API uses personal access tokens with bearer authentication. Get a token and copy-paste it into Authorize -> Bearer Auth. Don't forget to click on Authorize.
  4. Try it.

OpenAPI specification​

The JATOS API uses OpenAPI 3 for specification. You can use petstore.swagger.io to have an easy navigatable page.

This is the first version of the API. If you are missing endpoints please write an GitHub issue.

Authentication​

The JATOS API uses bearer authentication. It's pretty simple.

From swagger.io:

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name "Bearer authentication" can be understood as "give access to the bearer of this token." The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources.

Every HTTP request to the API needs this header (exchange <token> with your token)

Authorization: Bearer <token>

A command-line request with curl could look like:

curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://www.example.com/jatos/api/v1/admin/token

Personal access tokens​

The JATOS API uses personal access tokens (PATs or API tokens).

From wikipedia:

a personal access token (or PAT) is a string of characters that can be used to authenticate a user when accessing a computer system instead of the usual password. Though associated with a single account, multiple PATs may be created, and can be manipulated independently of the password associated with that account, including creation and revocation of PATs without altering the password.

Unlike other systems (e.g. GitHub) JATOS' tokens have no roles or scopes. A token has the same access as the user they are associated with. Needless to say a token can only be used to access studies including their result data if the associated user is a member of this study. Only admin tokens (tokens associated with an admin user) can access certain administration endpoints.

How to generate a token​

Go to your user's page (click on your name in the top-right header). Then click the button API Tokens.

API token 1

In the pop-up window click the button New Token". Then choose a descriptive _name (doesn't have to be unique). Choose the time period when the token is about to expire. Click Generate.

API token 1

Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

API token 1

In the token overview windows you can temporarily deactivate a token or delete it altogether.

API token 1

Deactivate the JATOS API​

By default the API is activated and ready to use. If, for whatever reasons, you want to turn it off, edit the conf/production.conf file in the JATOS installation folder. Search for jatos.api.allowed and remove the #:

jatos.api.allowed = false