Testimonials
What our customers say about Team Password Manager

API: Passwords

Current Team Password Manager version: 13.166.291

API v5

Sections: List passwords | Show a password | List of users who can access a password | Create a password | Update a password | Update security of a password | Update custom fields definitions of a password | Move a password | Archive/un-archive a password | Delete a password | Lock a password | Unlock a password | List files of a password | Upload a file to a password


List passwords

These return the passwords that the user has access to. The returned data is the same as in the passwords lists (all active, archived, favorite and search) in the web interface.

GET /passwords.json
GET /passwords/archived.json
GET /passwords/favorite.json
GET /passwords/search/urlencoded_string.json (see notes below)

The responses from these requests are paginated and /count.json and /page/num.json can be used. See the section on pagination for more information. Example: GET /passwords/page/2.json

If successful, the response code is 200 OK with the results of the call in the response body.

Example response body:

[
  {
    "id": 68,
    "name": "Wordpress admin",
    "project": {
      "id": 12,
      "name": "www.fictionalgadgetsite.com"
    },
    "notes_snippet": "some notes\nother notes",
    "tags": "wordpress",
    "access_info": "http:\/\/www.fictionalgadgetsite.com\/wp-admin",
    "username": "admin_sg",
    "email": "",
    "has_password": true,
    "expiry_date": "2013-10-20",
    "expiry_status": 2,
    "archived": false,
    "project_archived": false,
    "favorite": true,
    "num_files": 1,
    "locked": false,
    "locking_type": 0,
    "external_sharing": true,
    "linked": false,
    "updated_on": "2014-07-23 18:18:28"
  },
  {
    "id": 175,
    "name": "Sample password",
    "project": {
      "id": 12,
      "name": "www.fictionalgadgetsite.com"
    },
    "archived": false,
    "project_archived": false,
    "favorite": true,
    "locked": true,
    "locking_type": 1,
    "external_sharing": false,
    "linked": true,
    "updated_on": "2014-07-23 18:18:06"
  },
...
]

Notes:

  • expiry_date uses ISO 8601 format: yyyy-mm-dd.
  • expiry_status has the following values: 0=no date or not expired, 1=expires today, 2=expired, 3=will expire soon.
  • has_password is true if the password entry has the password datum filled in. To view it you need to use the show a password method.
  • Locked passwords (locked=true) will not show any data except id, name, project, archived, project_archived, favorite, locked, locking_type, external sharing, linked and updated on.
  • locking_type has the following values: 0=password not locked, 1=requires a reason to unlock, 2=requires permission to unlock.
  • Linked passwords: linked=true if the password is a linked password.
  • archived=true if the password is archived and/or the project is archived. project_archived=true if the project is archived.
  • Search:
    • You can use the search operators when searching for passwords.
    • You need to urlencode the "urlencoded_string" part.
    • Example (in PHP):
      $search_string = 'username:john'; // Find passwords whose username is "john"
$search_string_urlencoded = urlencode($search_string);
$request_url = 'https://YOUR_TPM_URL/index.php/api/v5/passwords/search/' . $search_string_urlencoded . '.json';

Show a password

This method returns all the data of a password, identified by its internal id.

GET /passwords/ID.json

If successful, the response code is 200 OK with the results of the call in the response body.

Example response body:

{
  "id": 69,
  "name": "CRM account",
  "project": {
    "id": 20,
    "name": "www.mynewsite.com"
  },
  "tags": "google",
  "access_info": "https:\/\/www.mynewsite.com\/crm",
  "username": "thisisme",
  "email": "thisisme@mynewsite.com",
  "password": "(Ip8=c1|9@%{d5!2-0.u",
  "expiry_date": "2015-08-24",
  "expiry_status": 3,
  "notes": "Some notes for the password",
  "custom_field1": {
    "type": "Text",
    "label": "Custom 1",
    "data": "Sample value"
  },
  "custom_field2": {
    "type": "Password",
    "label": "root",
    "data": "6Zi3=!\/7.b9#1,2}|4;"
  },
  "custom_field3": {
    "type": "One Time Password",
    "label": "Custom 2",
    "data": "725560",
  },
  "custom_field4": {
    "type": "Date",
    "label": "Renewal",
    "data": "2022-12-17"
  },
  "custom_field5": null,
  "custom_field6": null,
  "custom_field7": null,
  "custom_field8": null,
  "custom_field9": null,
  "custom_field10": null,
  "users_permissions": [
    {
      "user": {
        "id": 6,
        "username": "clairewood",
        "email_address": "claire@teampasswordmanager.com",
        "name": "Claire Wood",
        "role": "Normal user"
      },
      "permission": {
        "id": 20,
        "label": "Edit data"
      }
    },
    {
      "user": {
        "id": 7,
        "username": "janineblack",
        "email_address": "janine@teampasswordmanager.com",
        "name": "Janine Black",
        "role": "Normal user"
      },
      "permission": {
        "id": 0,
        "label": "No access"
      }
    }
  ],
  "groups_permissions": [
    {
      "group": {
        "id": 1,
        "name": "SEO"
      },
      "permission": {
        "id": 10,
        "label": "Read"
      }
    }
  ],
  "parents": [
    13,
    19,
    20
  ],
  "user_permission": {
    "id": 30,
    "label": "Manage"
  },
  "archived": false,
  "project_archived": false,
  "favorite": true,
  "num_files": 0,
  "locked": false,
  "locking_type": 0,
  "locking_request_notify": 0,
  "external_sharing": true,
  "external_url": "http:\/\/localhost\/tpm2\/site_enc\/index.php\/pwde\/view\/15abe2439e994f91befe55075b9729e6df514e4669",
  "linked": false,
  "source_password_id": 0,
  "managed_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  },
  "created_on": "2015-08-16 08:37:52",
  "created_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  },
  "updated_on": "2015-08-16 10:57:06",
  "updated_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  }
}

Notes:

  • expiry_date uses ISO 8601 format: yyyy-mm-dd.
  • Custom fields of type "Date" use ISO 8601 format: yyyy-mm-dd.
  • expiry_status has the following values: 0=no date or not expired, 1=expires today, 2=expired, 3=will expire soon.
  • Locked passwords (locked=true) will not show any data except id, name, project, archived, project_archived, favorite, locked, locking_type, external_sharing, linked and managed/created fields.
  • To view all the data for a locked password, the X-Unlock-Reason header must be supplied with a reason. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.
  • locking_type has the following values: 0=password not locked, 1=requires a reason to unlock, 2=requires permission to unlock.
  • locking_request_notify has the following values: 0=password not locked, 1=notify/request the password manager, 2=notify/request all the users with manage permission.
  • users_permissions is an array of objects of the following data: user object and permission object (permission id, description). Each object describes the permission set to the user on the password. These data are only available to users with manage permission on the password (they're set to null for users that don't have the manage permission).
  • groups_permissions is an array of objects of the following data: group object and permission object (permission id, description). Each object describes the permission set to the group on the password. These data are only available to users with manage permission on the password (they're set to null for users that don't have the manage permission).
  • parents is an array of project ids from the root to the project of the password (in descending order), as seen by the user.
  • user_permission is a permission object (permission id, description) that indicates what permission has the user making the request on the password.
  • Linked passwords: linked=true if the password is a linked password, and source_password_id has the id of the source password. Otherwise linked=false and source_password_id=0.
  • archived=true if the password is archived and/or the project is archived. project_archived=true if the project is archived.
  • Custom fields of type "One Time Password" return: in 10.135.236 the secret key in the "data" field and the OTP value at the time of the request in the "otp_value" field, in 10.138.240+ the "otp_value" field does not exist and the "data" field returns the OTP value at the time of the request.

List users who can access a password

This method returns the effective permissions users have on a password. This call shows similar data as the "Security" tab of the password.

GET /passwords/ID/security.json

To use this method with a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.

If successful, the response code is 200 OK with the results of the call in the response body.

This request is only available to the users who have manage permission on the password.

The response is an array of objects that have the following data:

  • User object: data about the user.
  • Permission object: permission id and description.
  • Granted via: how the user is granted the permission on the project.

Example response body:

[
  {
    "user": {
      "id": 2,
      "username": "alan",
      "email_address": "alan@teampasswordmanager.com",
      "name": "Alan",
      "role": "Project manager"
    },
    "permission": {
      "id": 30,
      "label": "Manage"
    },
    "granted_via": "Project: Project manager"
  },
  {
    "user": {
      "id": 4,
      "username": "amy",
      "email_address": "amy@teampasswordmanager.com",
      "name": "Amy",
      "role": "Normal user"
    },
    "permission": {
      "id": 10,
      "label": "Read"
    },
    "granted_via": "Group: SEO"
  },
  {
    "user": {
      "id": 3,
      "username": "ann",
      "email_address": "ann@teampasswordmanager.com",
      "name": "Ann",
      "role": "Normal user"
    },
    "permission": {
      "id": 10,
      "label": "Read"
    },
    "granted_via": "Group: SEO"
  },
  {
    "user": {
      "id": 6,
      "username": "clairewood",
      "email_address": "claire@teampasswordmanager.com",
      "name": "Claire Wood",
      "role": "Normal user"
    },
    "permission": {
      "id": 20,
      "label": "Edit data"
    },
    "granted_via": "User direct"
  },
  {
    "user": {
      "id": 7,
      "username": "janineblack",
      "email_address": "janine@teampasswordmanager.com",
      "name": "Janine Black",
      "role": "Normal user"
    },
    "permission": {
      "id": 0,
      "label": "No access"
    },
    "granted_via": "User direct"
  },
  {
    "user": {
      "id": 1,
      "username": "john",
      "email_address": "john@teampasswordmanager.com",
      "name": "John Boss",
      "role": "Admin"
    },
    "permission": {
      "id": 30,
      "label": "Manage"
    },
    "granted_via": "Password manager"
  }
]

Create a password

POST /passwords.json

The request body must include the data for the password. The required fields are the name and the id of the project the password is to be created in:

{
  "name": "Name of the password",
  "project_id": 21,
  ...
}

If successful, the response code is 201 Created with the internal id of the password in the response body:

{
  "id": 345
}

The following fields can be used when creating a password: 'name' (required), 'project_id' (required), 'tags' (list of comma separated strings), 'access_info', 'username', 'email', 'password', 'expiry_date' (in ISO 8601 format: yyyy-mm-dd, or null or ''), 'notes', 'custom_data1', 'custom_data2', 'custom_data3', 'custom_data4', 'custom_data5', 'custom_data6', 'custom_data7', 'custom_data8', 'custom_data9', 'custom_data10'.

Notes:

  • Custom data fields are allowed even if custom fields are not defined (their type is text by default).
  • The data for custom data fields of type "One Time Password" must be the secret key.
  • The data for custom data fields of type "Date" must be the specified in ISO 8601 format: yyyy-mm-dd.

Update a password

PUT /passwords/ID.json

The request body must include the data for the password. Only the fields that are included are updated, the other fields are left unchanged:

{
  "name": "Changed name of the password",
  "tags": "tag1,tag2,tag3",
  ...
}

If successful, the response code is 204 No content and the response body is empty.

The following fields can be used when updating a password: 'name', 'tags' (list of comma separated strings), 'access_info', 'username', 'email', 'password', 'expiry_date' (in ISO 8601 format: yyyy-mm-dd, or null or ''), 'notes', 'custom_data1', 'custom_data2', 'custom_data3', 'custom_data4', 'custom_data5', 'custom_data6', 'custom_data7', 'custom_data8', 'custom_data9', 'custom_data10'.

Notes:

  • The 'name', if present, cannot be empty.
  • Custom data fields are allowed even if custom fields are not defined (their type is text by default).
  • The data for custom data fields of type "One Time Password" must be the secret key.
  • The data for custom data fields of type "Date" must be the specified in ISO 8601 format: yyyy-mm-dd.
  • To update a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.
  • Linked passwords cannot be updated (they're read only). If you try to update a linked password you'll get a 403 Forbidden response.

Update the security of a password

PUT /passwords/ID/security.json

The request body must include the data for the password:

  • managed_by is the main manager of the password. If present, cannot be 0.
  • users_permissions is an array of [user_id, permission_id]. User permissions will be set for the users passed, deleting the current permissions. permission_id can be: 0=no acces, 10=read, 20=edit data, 30=manage (only 0, 10 for users with role read only). If you want to set "Do not set", simply exclude the user. Admin users, the project manager(s) and the password manager can be included in this list, but it will have no effect. For Read only users these are the only valid permissions: 0, 10.
  • groups_permissions is an array of [group_id, permission_id]. Groups permissions will be set for the groups passed, deleting the current permissions. permission_id can be: 0=no acces, 10=read, 20=edit data, 30=manage. If you want to set "Do not set", simply exclude the group from the list.

Note: you cannot assign the "20=edit data" permission to linked passwords as they're read only. You'll get a 409 Conflict response if you try to do so.

Example of a request body:

{
  "managed_by": 1,
  "users_permissions": [ [2,10],[3,20] ],
  "groups_permissions": [ [1,20] ]
}

If successful, the response code is 204 No content and the response body is empty.

To update the security of a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.

To get the users in your Team Password Manager installation you can use GET /users.json and the groups GET /groups.json.


Update custom fields definitions of a password

PUT /passwords/ID/custom_fields.json

The request body must include the data for the password. Only the fields that are included are updated, the other fields are left unchanged:

{
  "custom_label1": "MySQL user",
  "custom_type1": "text",
  "custom_label2": "MySQL password",
  "custom_type2": "password",
  ...
}

If successful, the response code is 204 No content and the response body is empty.

The following fields can be used when updating a password's custom fields definitions: custom_labelX, custom_typeX (X=1..10).

Allowed custom types (case insensitive): 'Text', 'Encrypted text', 'E-mail' or 'email, 'Password', 'Notes', 'Encrypted notes', "One Time Password" or "OTP" and "Date".

Notes:

  • To delete the definition of a custom field set custom_typeX to an empty string.
  • Deleting the definition of a custom field doesn't delete its data, but it may uncrypt it.
  • No data is passed here, only definition.
  • To update the custom field definitions of a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a 409 Conflict error will be returned.
  • Custom field definitions of linked passwords cannot be updated (they're read only). If you try to update the custom field definition of a linked password you'll get a 403 Forbidden response.

Move a password

Move a password to another project.

PUT /passwords/ID/move.json

The request body must include the ID of the target project:

{
  "project_id": 123
}

Note: project_id cannot be 0.

If successful, the response code is 204 No content and the response body is empty.

To move a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.


Archive/un-archive a password

PUT /passwords/ID/archive.json

PUT /passwords/ID/unarchive.json

If successful, the response code is 204 No content and the response body is empty.

To archive/un-archive a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.


Delete a password

DELETE /passwords/ID.json

This deletes the password, its files, etc.

If successful, the response code is 204 No content and the response body is empty.

To delete a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.

Notes:

  • linked passwords cannot be deleted (they're read only). If you try to delete a linked password you'll get a 403 Forbidden response.
  • Since v. 12.143.260, the password is moved to the Trash Bin.

Lock a password

PUT /passwords/ID/lock.json

This sets the locking status of a password to locked. From this moment on, any user who wants to use it will have to supply a reason to unlock it.

If successful, the response code is 204 No content and the response body is empty.


Unlock a password

PUT /passwords/ID/unlock.json

This sets the locking status of a password to unlocked.

If successful, the response code is 204 No content and the response body is empty.

To unlock a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.


List files of a password

This method returns the files uploaded to a password. This call shows similar data as the "Files" tab of the password.

GET /passwords/ID/files.json

To use this method with a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.

The response from this request is paginated and /count.json and /page/num.json can be used. See the section on pagination for more information. Example: GET /passwords/ID/files/page/2.json

If successful, the response code is 200 OK with the results of the call in the response body.

The response is an array of objects that have the following data: id (each file has a unique id in Team Password Manager, which you can see by clicking on the "Info" button of the file), filename, size in bytes and as it appears in the UI, a snippet of the notes if the file has them and when it was last updated.

Example response body:

[
  {
    "id": 65,
    "filename": "cat.jpg",
    "size_bytes": 82935,
    "size_txt": "80.99 kb",
    "notes_snippet": "A little ...",
    "updated_on": "2021-07-15 13:00:48"
  },
  {
    "id": 67,
    "filename": "dog.jpg",
    "size_bytes": 82935,
    "size_txt": "80.99 kb",
    "notes_snippet": "",
    "updated_on": "2019-11-04 17:31:26"
  },
  {
    "id": 58,
    "filename": "server_instructions.pdf",
    "size_bytes": 92655,
    "size_txt": "90.48 kb",
    "notes_snippet": "",
    "updated_on": "2019-04-25 13:37:00"
  }
]

Upload a file to a password

This method uploads a file to a password.

POST /passwords/ID/upload.json

The request body must include the data for the file, which consists of three fields:

  • file_data_base64 contents of the file. It must be Base64 encoded. This field is required.
  • file_name name of the file. This field is required.
  • notes notes of the file. This field is optional.

Example request body:

{
  "file_data_base64": "dGhpcyBpcyBhIHNpbXBsZSB0ZXh0IGZpbGU=", (Base64 encoded content of the file to upload)
  "file_name": "file_to_upload.pdf",
  "notes": "some notes for the file"
}

If successful, the response code is 201 Created with the internal id of the file in the response body:

{
  "id": 373
}

To use this method with a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.


Upload a file to a password example in PHP

The following script shows you how to upload a file to a password using PHP. To run it, save it to a PHP file and replace the variables on top with your own values:

<?php
  // API v5 URL
  $tpm_base_url  = 'https://YOUR_TPM_URL/index.php/api/v5';

  // User with Edit data / Manage permission on the password to upload the file to
  $username = 'YOUR_TPM_USERNAME';
  $password = 'YOUR_TPM_PASSWORD';

  // Password id of the password to upload the file to
  $pwd_id = YOUR_PWD_ID; // For example: 344

  // File to upload, in the same folder as this script
  $file_to_upload = 'YOUR_FILE_NAME'; // For example: 'server_specs.pdf'

  // Read the file, encode it with Base64 and store it in $file
  $file = base64_encode(file_get_contents($file_to_upload));
  if ( $file ) {
    // Method to upload
    $request_uri = '/passwords/' . $pwd_id . '/upload.json';

    // Body with the data to upload the file (JSON encoded array)
    $request_body_json = json_encode(array(
      'file_data_base64' => $file,
      'file_name' => $file_to_upload, // Just the name of the file, do not include the path here
      'notes' => 'Some notes'
    ));

    // Headers: JSON and UTF-8
    $headers = array(
      'Content-Type: application/json; charset=utf-8'
    );

    // POST request
    $ch = curl_init($tpm_base_url . $request_uri);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_HEADER, FALSE); // Does not include header in the output
    curl_setopt($ch, CURLOPT_POST, TRUE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $request_body_json);
    curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password); // HTTP Basic Authentication
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    
    // Execute
    $result = curl_exec($ch); 
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    // Show response
    echo 'Status: ' . $status . '<br/>';
    echo $result;

  } else {
    echo 'Incorrect file';
  }

If successful, the result should show something like this, where "id" is the id of the newly created file:

Status: 201
{"id":380}

Document changelog

May 30, 2023: Since v. 12.143.260, when deleting a password, it's moved to the Trash Bin.
Feb 15, 2022: Custom fields of type OTP return only the OTP value in 10.138.240+.
Nov 12, 2021: Document created
Questions or Problems? Please contact our support department