API & integrations
Python connector
12min
description the python client is used to interact with the passwork password management system api it ensures secure storage, retrieval, and management of passwords with support for client side encryption requirements python 3 10+ requests >= 2 31 0 python dotenv >= 1 0 0 cryptography >= 42 0 0 pbkdf2 >= 1 3 installation the package can be installed directly from github shell pip install git+ssh //git\@github com\ passwork me/passwork python git alternatively, install via https shell pip install git+https //github com/passwork me/passwork python git features client side encryption with master password support; automatic token refresh; encrypted session storage and restoration; multi layer encryption (pbkdf2, rsa, aes); attachment management; user and role management; vault (storage) management; password sharing via inbox; support for custom fields; tag system advanced usage passwork version 7 utilizes a limited lifetime token mechanism access token the primary token for authorizing requests it has a limited validity period (usually a few minutes or hours); refresh token a long lived token used to obtain a new access token without re authenticating session management the connector can store and use tokens, and in case the access token expires, it can automatically refresh the tokens (if a refresh token is provided) python # enable token usage and automatic token refresh during authorization passwork = passworkclient(host, true, true) \# load and decrypt tokens from the session file to use in the current scenario passwork load session("session file", "p2eyn+vthh27hno2plpwwoxfoz0ufnlzubdeclupcsu=") \# save tokens from the current scenario to the session file in encrypted form encryption key = passwork save session("session file", "p2eyn+vthh27hno2plpwwoxfoz0ufnlzubdeclupcsu=", true) example scenario with automatic token refresh python import sys import os from passwork client import passworkclient \# configuration access token = "" refresh token = "" # optional (if you need to refresh access token) master key = "" # master key (if client side encryption is enabled) host = "https //passwork" # passwork host \# login to passwork try passwork = passworkclient(host, true, true) passwork set tokens(access token, refresh token) if bool(master key) passwork set master key(master key) except exception as e print(f"error {e}") exit(1) \# load and decrypt tokens from the session file to use in the current scenario \#passwork load session("session file", "p2eyn+vthh27hno2plpwwoxfoz0ufnlzubdeclupcsu=") \# example create vault try vault name = "python vault" vault id = passwork create vault(vault name) print(f"vault was created {vault id}") except exception as e print(f"error {e}") \# save tokens from the current scenario to the session file in encrypted form encryption key = passwork save session("session file", "p2eyn+vthh27hno2plpwwoxfoz0ufnlzubdeclupcsu=", true) on the first run , the line for loading tokens from session file should be commented out — since the tokens haven’t been saved yet on subsequent runs, the line should be uncommented to use the previously saved tokens python passwork load session("session file", "p2eyn+vthh27hno2plpwwoxfoz0ufnlzubdeclupcsu=") password management create a password with custom fields and tags python import sys import os from passwork client import passworkclient \# configuration access token = "" refresh token = "" # optional (if you need to refresh access token) master key = "" # master key (if client side encryption is enabled) host = "https //passwork" # passwork host \# login to passwork try passwork = passworkclient(host) passwork set tokens(access token, refresh token) if bool(master key) passwork set master key(master key) except exception as e print(f"error {e}") exit(1) \# example create item try vault id = "" color = 8 \# example custom fields custom fields = \[ { "name" "text field", "value" "field value", "type" "text" }, { "name" "custom password", "value" "secret123!", "type" "password" }, { "name" "totp", "value" "abcdefghijklmnop", "type" "totp" } ] \# prepare item data item data = { "vaultid" vault id, "name" "new item", "login" "test user", "password" "test password123!", "url" "https //example com", "description" "item description", "color" color, "tags" \["tag1", "tag2"], "customs" custom fields } \# create item item id = passwork create item(item data) print(f"item created with id {item id}") \# get the created item item = passwork get item(item id) print(f"created item {item}") except exception as e print(f"error {e}") update an existing password python import sys import os from passwork client import passworkclient \# configuration access token = "" refresh token = "" # optional (if you need to refresh access token) master key = "" # master key (if client side encryption is enabled) host = "https //passwork" # passwork host \# login to passwork try passwork = passworkclient(host) passwork set tokens(access token, refresh token) if bool(master key) passwork set master key(master key) except exception as e print(f"error {e}") exit(1) \# example update item try \# id of the item to update item id = "" vault id = "" \# get current item item = passwork get item(item id) print(f"current item {item}") \# prepare updated data updated data = { "vaultid" vault id, "name" "updated item name", "login" "updated user", "password" "updated password 456!", "url" "https //updated example com", "description" "updated description", "tags" \["updated", "tag2", "tag3"], "customs" \[ { "name" "updated custom field", "value" "updated value", "type" "text" }, { "name" "updated password field", "value" "newsecret456!", "type" "password" } ] } \# update the item passwork update item(item id, updated data) \# get the updated item updated item = passwork get item(item id) print(f"updated item {updated item}") except exception as e print(f"error {e}") delete a password python import sys import os from passwork client import passworkclient \# configuration access token = "" refresh token = "" # optional (if you need to refresh access token) master key = "" # master key (if client side encryption is enabled) host = "https //passwork" # passwork host \# login to passwork try passwork = passworkclient(host) passwork set tokens(access token, refresh token) if bool(master key) passwork set master key(master key) except exception as e print(f"error {e}") exit(1) \# example delete item try \# id of the item to delete item id = "" \# delete the item bin item id = passwork delete item(item id) print(f"item deleted bin item id {bin item id}") except exception as e print(f"error {e}") user management create a new user python import sys import os from passwork client import passworkclient \# configuration access token = "" refresh token = "" # optional (if you need to refresh access token) master key = "" # master key (if client side encryption is enabled) host = "https //passwork" # passwork host \# login to passwork try passwork = passworkclient(host) passwork set tokens(access token, refresh token) if bool(master key) passwork set master key(master key) except exception as e print(f"error {e}") exit(1) \# example create user try \# fetch available user roles roles response = passwork call("get", "/api/v1/user roles", {"includeuserrole" '1', "isonlymanageable" '1'}) if not roles response or not roles response get("items") print("error could not fetch user roles or no manageable roles found ") exit(1) \# find the 'user' role (adjust if needed) user role items = \[r for r in roles response\["items"] if r get("code") == "user"] if not user role items print("error default 'user' role not found ") exit(1) default user role id = user role items\[0]\["id"] \# define user data user data = { "email" "test user python\@example com", "fullname" "python test user", "login" "python test user", "userroleid" default user role id, } \# create the user new user = passwork create user(user data) \# construct the success message message = f"user '{user data\['fullname']}' created with id {new user\['user id']}" if 'password' in new user and new user\['password'] message += f", password {new user\['password']}" if 'master password' in new user and new user\['master password'] message += f", master password {new user\['master password']}" print(message) except exception as e print(f"error {e}") direct api calls for operations not covered by helper methods python # direct api call response = client call("delete", f"/api/v1/folders/{folder id}") documentation detailed examples are available in the examples directory of the repository