API: Authentication

API v6

All requests to the Team Password Manager API must be authenticated.

Access to the API is done at the user level, meaning that any user of a Team Password Manager installation can access the API using his/her credentials. This way, the permissions the user has on the resources are the same as when the user accesses the software via the web interface. For instance, users with "Admin" role will have access to all of the resources while users with other roles will have access to less resources.

The API provides two methods for authenticating requests: HTTP Basic Authentication and HMAC Authentication.

This document explains these two methods and a couple of settings related to them:

• HTTP Basic Authentication
• HMAC Authentication
• Choosing the API Authentication Method
• Setting the HMAC API Keys Expiration

HTTP Basic Authentication

HTTP basic authentication is the easiest and simplest way to authenticate API requests in Team Password Manager.

It consists on sending with the request the username and password of the user who makes the request. Because of this we do not recommend HTTP basic authentication if your installation of Team Password Manager is using http. If your installation uses https then this is secure because all data are transmitted encrypted.

Note that if the user is an LDAP user, Team Password Manager will transparently authenticate the API request using LDAP, like if the user were signing in from the web interface.

Also note that API authentication will NOT use Two-factor authentication if the user has 2FA enabled.

Here's how you do HTTP basic authentication with curl and PHP:

With curl:

curl -u username:password

With PHP:

curl_setopt($ch, CURLOPT_USERPWD, 'username' . ":" . 'password');

Here you have a complete example (get the list of passwords) with an API request using this type of authentication:

curl

curl -u username:password \
  -H 'Content-Type: application/json; charset=utf-8' \
  -i https://tpm.mydomain.com/index.php/api/v6/passwords.json

PHP

<?php	
  // Parameters
  $tpm_base_url = 'https://tpm.mydomain.com/index.php/'; // ending with /
  $req_uri = 'api/v6/passwords.json'; // GET /passwords.json
  $username = 'YOUR USERNAME';
  $password = 'YOUR PASSWORD';

  // Request headers
  $headers = array(	
    'Content-Type: application/json; charset=utf-8'
  );

  // Request
  $ch = curl_init($tpm_base_url . $req_uri);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
  curl_setopt($ch, CURLOPT_HEADER, TRUE); // Includes the header in the output
  curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password); // HTTP Basic Authentication
  $result = curl_exec($ch);	
  $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);	
  curl_close($ch);

  // Get headers and body
  list($headers, $body) = explode("\r\n\r\n", $result, 2);
  $arr_headers = explode("\r\n", $headers);
  $arr_body = json_decode($body, TRUE);

  // Show status and array of passwords
  echo 'Status: ' . $status . '<br/>';
  print_r($arr_body);

HMAC Authentication

HMAC (Hash Message Authentication Code) authentication is more complex to use but we consider it more secure, specially if your Team Password Manager installation is using http.

HMAC authentication in Team Password Manager works this way:

1. A user in Team Password Manager has a public key and a private key ("API Keys" tab in "My Account").
2. The application using the API creates a unique HMAC (a hash) that represents the request. This hash is created using the private key combining a part of the request URL with a timestamp and the request body (if it exists).
3. The application sends the request with the public key and the HMAC, as well as the rest of the data.
4. Team Password Manager looks for the public key in the user database, retrieves its corresponding private key and tries to re-create the HMAC using the received request data.
5. Team Password Manager then compares the two HMACs. If they're equal, the request is authorized.

As you can see only the public key of the user is transmitted. The private key is a secret that only Team Password Manager and the client application know, and it's never transmitted.

Making API requests using HMAC authentication

Let's put the concept into practice using PHP. You can also use curl or the language of your choice, but we find it easier to explain it using PHP.

Note: if you want to use this authentication method, the Hash extension (http://php.net/manual/en/book.hash.php) must be installed and the "sha256" algorithm present.

Let's create a project in Team Password Manager (POST /projects.json) with a request authenticated using HMAC:

1. Get the public and private keys of your user

Click on your name on the top menu ("My account") and get the keys from the "API keys" tab (if you don't see this tab it means that API access is disabled):

2. Create the HMAC (hash)

To create the HMAC you have to concatenate these 3 elements and then apply the hash_hmac() function with the "sha256" algorithm and the private key:

1. The URL part that starts after "index.php/". Example:

https://tpm.mydomain.com/index.php/api/v6/projects.json

This value can't have any leading or trailing "/".

2. A timestamp created with the time() function.

3. The request body (a json string):

$request_body = json_encode(array(
  'name' => 'This is a new password',
  'parent_id' => 0 // root project
));

So, the HMAC ($hash) would be:

$timestamp = time();
$unhashed = 'api/v6/projects.json' . $timestamp . $request_body;
$hash = hash_hmac('sha256', $unhashed, $private_key);

Note: this hash value must be in lowercase. Take this into consideration if the system you're using defaults to uppercase.

3. Create the headers

You need to send the following headers to be able to authenticate using HMAC:

• X-Public-Key: the public key of the user.
• X-Request-Hash: the HMAC calculated in step 2.
• X-Request-Timestamp: the timestamp from step 2.

So, in PHP this would be:

$headers = array(
  'X-Public-Key: ' . $public_key, 
  'X-Request-Hash: ' . $hash,
  'X-Request-Timestamp: ' . $timestamp,	
  'Content-Type: application/json; charset=utf-8' // required in every request
);

4. Create the rest of the request and send it

Here you have the full code:

<?php		
  // POST /projects.json with HMAC authentication

  // Parameters
  $tpm_base_url = 'https://tpm.mydomain.com/index.php/'; // ending with /
  $req_uri = 'api/v6/projects.json'; // no beginning or trailing /
  $public_key = 'YOUR PUBLIC KEY';
  $private_key = 'YOUR PRIVATE KEY';

  // Body (json encoded array)
  $request_body = json_encode(array(
    'name' => 'This is a new project',
    'parent_id' => 0 // root project
  ));

  // Calculate the HMAC ($hash)
  $timestamp = time();
  $unhashed = $req_uri . $timestamp . $request_body;
  $hash = hash_hmac('sha256', $unhashed, $private_key);

  // Request headers
  $headers = array(
    'X-Public-Key: ' . $public_key,
    'X-Request-Hash: ' . $hash,
    'X-Request-Timestamp: ' . $timestamp,	
    'Content-Type: application/json; charset=utf-8'
  );

  // Request
  $ch = curl_init($tpm_base_url . $req_uri);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
  curl_setopt($ch, CURLOPT_HEADER, TRUE); // Includes the header in the output
  curl_setopt($ch, CURLOPT_POST, TRUE);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $request_body);
  $result = curl_exec($ch);	
  $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);	
  curl_close($ch);

  // Get headers and body
  list($headers, $body) = explode("\r\n\r\n", $result, 2);
  $arr_headers = explode("\r\n", $headers);
  $arr_body = json_decode($body, TRUE);

  // Show status and the new project id
  echo 'Status: ' . $status . '<br/>';
  print_r($arr_body);

Note that here there isn't the call to curl_setopt with the username and password used in HTTP Basic Authentication.

Choosing the API Authentication Method

You can select the preferred authentication method for your Team Password Manager installation by navigating to Settings (located in the top menu), then selecting API from the left sidebar, and clicking on Edit API Authentication Method.

On the Edit API Authentication Method screen, you’ll have three options:

• HTTP Basic and HMAC (default): Both authentication methods are allowed, so API requests can use either.
• HTTP Basic only: Only HTTP Basic authentication is permitted for API requests.
• HMAC only: Only HMAC authentication is permitted for API requests.

The selected API authentication method a global setting that affects all users.

Setting the HMAC API Keys Expiration

If HMAC authentication is enabled in your Team Password Manager installation, you can set the duration for which HMAC API keys remain valid or choose to make them valid indefinitely.

To do it, go to Settings (top menu), then select API from the left sidebar, and click on Edit HMAC API Keys Expiration.

On the Edit HMAC API Keys Expiration screen you can set the days until API Keys expire, from 1 to 999. You set this value to 0 to disable expiration:

Users can see the expiration date on the API Keys tab in My Account. If the API keys have expired, they'll also see an Expired label next do the date:

For API only users, you can see the same information on the API Keys tab on the user screen.

If the HMAC API keys have expired, the user can renew them by clicking the Renew API Keys button on the API Keys tab, as shown in the screenshot above.

If an HMAC authenticated request fails due to the HMAC Keys being expired, the response is 401 Unauthorized with the message "HMAC API key has expired".

The HMAC API Keys expiration setting is a global setting that affects all users.