1. Authentication

1.1. Overview

The REST API is accessible both anonymously and with authentication although some resources are accessible with authentication only. When authentication is required you will get a 401 HTTP error code.

Note

Note that invalid credentials will result in a server error even if the resource is accessible anonymously.

1.2. Personal access key authentication

Personal access keys are the preferred way for scripts and third party applications to authenticate with the REST API.

1.2.1. Creating a personal access key

You can create as many personal access keys as you need for your account preferences.

  1. Log in to your account

  2. Go to your account preferences

  3. Find the section about personal API access keys

  4. Click on Generate new key

  5. Choose the scope REST

  6. Optionally add description to help you distinguish your new key from the others

  7. Click on Generate new key

  8. Save the access key somewhere safe. Once you leave or refresh the page there is no way to retrieve it again.

If you do not need an personal access key anymore or if one your personal access key has been compromised, you can delete them any time in the same section.

More information in Access Keys

1.2.2. Use of a personal access key

You must include the personal access key you have generated in a custom header X-Auth-AccessKey.

Example:

$ curl -XGET --header 'Content-type: application/json' \
  --header 'X-Auth-AccessKey:  tlp.k1.1026…' \
  https://tuleap.example.com/api/projects/112

1.3. OAuth2 Access Token Authentication

OAuth2 Access Tokens are another secure method for third party applications to authenticate with Tuleap’s REST API.

In order to use this method, a Project Administrator must first register the third-party application in Tuleap.

Once registration is made and the application has been authorized to access Tuleap by an end-user, it will need to provide its OAuth2 Access Token as described in RFC6750 using the Authorization Header field.

Please note that ONLY the Authorization Header method is supported. Using the Form-Encoded Body Parameter or URI Query Parameter is NOT supported by Tuleap.

1.4. Token-based Authentication

Warning

Usage of the token-based authentication is deprecated, a personal access key should be used instead. Personal access keys will give you a clearer picture of what has accesses to your account and when it was accessed for the last time. The use of a personal access key is similar to that of a token, the migration of existing uses should be relatively easy.

The general principle is to issue a request to the /api/tokens route to get a token and re-use this token later-on to prove identity.

1.4.1. Authentication

Request:

POST /api/tokens

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "user_id": "115",
  "token": "abcd",
  "uri": "/api/tokens/abcd"
}

Example:

$ curl -XPOST --header 'Content-type: application/json' \
  -d '{"username":"john_doe", "password":"weakpassword"}' \
  https://tuleap.example.com/api/tokens

1.4.2. Use of the token

You must include 2 custom headers in your request:

  • X-Auth-Token: value of token attribute received from /api/tokens

  • X-Auth-UserId: value of user attribute received from /api/tokens

Example:

$ curl -XGET --header 'Content-type: application/json' \
  --header 'X-Auth-Token: abcd' \
  --header 'X-Auth-UserId: 115' \
  https://tuleap.example.com/api/projects/112

Important

A token lasts for 24 hours. Once it expires you will get a 401 HTTP error code. Your client will have to issue another token.

1.5. HTTP Basic authentication

Warning

You should use a personal access key as it helps to manage the risk of leaking a password and can be easily revoked. You will also get better performances when using a personal access key.

In order to authenticate, simply add your username and password to each request.

Example:

$ curl -XGET --header 'Content-type: application/json' \
  -u username:password \
  https://tuleap.example.com/api/projects/112

1.6. Conclusions

Now that we are able to do authenticated calls we can continue to data retrieval in next section Query the artifacts.