The Team Password Manager API

API v6

Team Password Manager's RESTful API (Application Programming Interface) allows other applications to access some of the resources of the software, like projects or passwords. This document describes the basic concepts of the API and provides a quick example to get you started using it.

Sections: Overview | Enabling and disabling API access | Security | Making requests | Authentication | JSON only | Responses and error handling | Pagination | Logging | Maintenance Mode | Resources | Examples

Overview

Team Password Manager's API has the following features:

• REST (Representational state transfer): external applications can access the resources provided by the API by using standard HTTP methods (GET, POST, PUT, DELETE).
• JSON: all requests and responses use JSON.
• Two methods for authenticating: HMAC and HTTP Basic authentication. Any (active) user can access the API using one of these two methods.
• API access can be enabled/disabled globally in Settings.
• It's versioned. You're reading the docs corresponding to version 6 (v6). You can see which version of the API your installation supports by going to Settings in the top menu and then select API.
• It's NOT available in the demo. If you want to try it you should get a trial license.

API v6 provides access to the following resources in Team Password Manager: projects, passwords, my passwords, files, favorites, users, groups, passwords generator, version and the log.

Enabling and disabling API access

API access is disabled by default. To enable it, go to Settings in the top menu, choose the API tab and click on "Enable API access". Once enabled it can be disabled using the same screen.

If access to the API is disabled, calls to it return 403 Forbidden, with the message "API access is disabled".

API access cannot be enabled on the online demo.

Security

Since version 7.103.208 there's a way to limit the users who can access the API: you can either configure it so that all users can access the API (default) or that only "API only" users can access it. You can change this setting when the API is enabled in Settings (top menu), then API (sidebar) and then click on "Edit API Security".

Making requests

There are 3 required elements to make a request to Team Password Manager's API: the URL, the Content-Type header and the authentication parameters.

URLs

Requests to the Team Password Manager API must follow this URL schema:

YOUR_TEAM_PASSWORD_MANAGER_URL/index.php/api/v6/resource_and_parameters.json

Example: to get a list of passwords of a Team Password Manager installation located at https://tpm.mydomain.com, the URL is:

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

Note: API access also works with http if your installation is using http (https is recommended).

Content-Type header

Calls to the API must always supply the following Content-Type header: Content-Type: application/json; charset=utf-8

If you don't supply this header, you will get a 415 Unsupported Media Type response.

Authentication parameters

All requests to the API must be authenticated. See the section on authentication on how to do it.

Quick example

Here you have an example using curl from the command line to make a GET request to fetch the list of passwords for a user using HTTP Basic Authentication:

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

To try it with your Team Password Manager installation, replace "username" and "password" with your credentials and "https://tpm.mydomain.com" with the URL of your installation.

Authentication

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: uses the username and password of the user.
• HMAC Authentication: uses the user's HMAC API Keys (in the "API Keys" tab in My Account) to calculate a hash of the request.

Since v. XX.XXX.XXX:

• You can configure which authentication method is enabled for the API: both HTTP Basic and HMAC, HTTP Basic only, or HMAC only.
• You can set whether HMAC API keys will expire after a specified number of days or remain valid indefinitely.

Head over to the API authentication document to learn how to authenticate API requests.

JSON only

The Team Password Manager's API only supports JSON (JavaScript Object Notation) for serialization of data, in requests and responses.

All API URLs end in .json to indicate that they accept and return JSON.

The character set in requests and responses is UTF-8.

Responses and error handling

Any call to the API returns one of the three following responses:

1. Ok response with status code 2XX

Usually 200 Ok in GET requests, 201 Created in POST requests when creating resources and 204 No Content in PUT and DELETE requests that return no content.

If content is returned in the response body it's a JSON object/array.

2. Error response with status code 4XX

The request cannot be executed and the error is described in the response body with the following JSON object:

{
  "error": true,
  "type": "Description of the status code error",
  "message": "Description of why the request failed"
}

A failed HTTP Basic authentication request, for instance, returns status code 401 Unauthorized with the following JSON object:

{
  "error": true,
  "type": "Unauthorized",
  "message": "Incorrect or missing username or password"
}

3. Error response with status code 500

500 Internal Server Error indicates an unhandled exception on the server side.

The response also includes a JSON object describing the error.

Pagination

Some requests return lists in the form of a JSON array of objects. For example, the endpoint GET /passwords.json returns a list of passwords that the user can access. These responses are generally paginated, but not always. Each resource's documentation specifies whether pagination applies.

If pagination applies for an endpoint, the way to get the different pages is using page and the number of the page that needs to be returned, this way: GET /passwords/page/X.json (X=the page to be returned).

When there are more results available for a request, the following link relations (rel) are present in the Link response header:

• self: Refers to the URL of the current page in the request.
• prev: Points to the previous page, if available.
• next: Points to the next page, if there is one.
• first: Directs to the first page in the set.
• last: Directs to the last page in the set.

For example, when requesting the second page of the passwords list:

Link: <https://tpm.mydomain.com/index.php/api/v6/passwords/page/2.json>; rel="self",
<https://tpm.mydomain.com/index.php/api/v6/passwords/page/1.json>; rel="prev",
<https://tpm.mydomain.com/index.php/api/v6/passwords/page/3.json>; rel="next",
<https://tpm.mydomain.com/index.php/api/v6/passwords/page/1.json>; rel="first",
<https://tpm.mydomain.com/index.php/api/v6/passwords/page/100.json>; rel="last"

Some notes:

• If the response has only one page or doesn't have any data, only the self rel is returned.
• If the response is the last page of the set, the next rel is not returned.
• If the response is the first page of the set, the prev rel is not returned.
• If a page number specified in the request is too high, a 404 Not Found error will be returned with the message "The page number is too high". In the example above, that would be if using this request: https://tpm.mydomain.com/index.php/api/v6/passwords/page/101.json
• Specifying no page, page 0 or page 1 in the request are equivalent. They all return the first page. Examples: https://tpm.mydomain.com/index.php/api/v6/passwords.json
https://tpm.mydomain.com/index.php/api/v6/passwords/page/0.json
https://tpm.mydomain.com/index.php/api/v6/passwords/page/1.json

Note that before API v.6 only the next rel was returned.

Setting the page size

The default page size is 20 elements. This applies to lists of the user interface and paginated results of the API. This default value can be changed using the NUM_ITEMS_LISTS configuration setting.

Since API v.6 you can set the page size for individual requests using the X-Page-Size header. When using this header in a request, the page size will only be applied to this request, regardless of the global page size. The value for X-Page-Size must be an unsigned integer number between 5 and 1000 (both included). For example:

X-Page-Size: 100

Note that some lists may take long to return with a high X-Page-Size value.

Count

You can also manage pagination for these resources using the count.json endpoint, which returns the number of elements and pages a resource has. For example:

GET /passwords/count.json
{
  "num_items": 211,
  "num_pages": 11,
  "num_items_per_page": 20
}

You should use X-Page-Size with count to get the correct results for a specific page size.

Logging

Team Password Manager logs all actions that are generated by API requests. The actions are the same as in the web interface, so there's a column in the log called "Origin" that tells where the action originated:

In the main log screen this column can be used to filter log entries.

Requests that result in an error are not logged except for 401 Unauthorized.

Maintenance Mode

If Maintenance Mode is enabled the API is not available and any requests return "Service Unavailable" (status code 503), with the message: "This installation is in Maintenance Mode.".

Resources

With Team Password Manager's API v6 you can access the following resources:

• Projects: list, show, create, update, get a list of passwords from a project, get a list of users who can access the project, archive/unarchive, list files, upload a file and delete.
• Passwords: list, show, create, update, update security, update custom fields definitions, get a list of users who can access the password, delete, archive/unarchive, move, list files, upload a file and lock/unlock.
• My Passwords: list, show, create, update and delete.
• Files: list files, show a file, update the notes of a file, get the max upload file size, get the uploads folder information, upload a file, download a file, delete a file.
• Favorites: list favorite passwords and projects for the user, make a password/project favorite and make a password/project not favorite.
• Users: list, show, create, update, activate/deactivate, convert to ldap/normal and delete.
• Groups: list, show, create, update, add user to group, delete user from group and delete.
• Passwords generator: get a strong, random password generated by the password generator with the current settings.
• Version: get version information.
• The log: query the log.

Examples

Here you have some examples to get you started with the API.

They all use HTTP Basic Authentication. To use them in your installation change "username", "password" and "https://tpm.mydomain.com".

Passwords list (first page)

GET /passwords.json

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);
  $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);

Show a password

To get all the data of a password you need its internal id. Example for id=1: GET /passwords/1.json

curl

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

PHP

Use the code from the previous example and just change the $req_uri variable to:

$req_uri = 'api/v6/passwords/1.json'; // GET /passwords/1.json

Create a project

POST /projects.json

Only the name is required to create a project. If successful it returns 201 Created and the id of the new project:

{
  "id": 41
}

curl

curl -u username:password \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"name":"My new project", "parent_id": 0}' \
  -i https://tpm.mydomain.com/index.php/api/v6/projects.json

PHP

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

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

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

  // 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);
  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);

Create a password

POST /passwords.json

Only the name and the id of the project where the password goes is required to create a password. If successful it returns 201 Created and the id of the new password:

{
  "id": 123
}

curl

curl -u username:password \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"name":"My new password", "project_id":41}' \
  -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'; // POST /passwords.json
  $username = 'YOUR USERNAME';
  $password = 'YOUR PASSWORD';
  $project_id = 41; // The id of the project where the password is created

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

  // Body (json encoded array)
  $request_body = json_encode(array(
    'name' => 'This is a new password',
    'project_id' => $project_id,
    'tags' => 'seo,clients',
    'access_info' => 'http://urlforthepassword.com',
    'username' => 'usernameforthepassword',
    'email' => 'email@forthepassword.com',
    'password' => 'changeit'
  ));

  // 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);
  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 password id
  echo 'Status: ' . $status . '<br/>';
  print_r($arr_body);