-
Notifications
You must be signed in to change notification settings - Fork 42
Password Api
Property | Type | Writable | Encrypted | Versioned | Description |
---|---|---|---|---|---|
id | string | no | no | no | The UUID of the password |
label | string | yes | yes | yes | User defined label of the password |
username | string | yes | yes | yes | Username associated with the password |
password | string | yes | yes | yes | The actual password |
url | string | yes | yes | yes | Url of the website |
notes | string | yes | yes | yes | Notes for the password. Can be formatted with Markdown |
customFields | string | yes | yes | yes | Custom fields created by the user. (See custom fields |
status | int | no | no | yes | Security status level of the password (0 = ok, 1 = user rules violated, 2 = breached) |
statusCode | string | no | no | yes | Specific code for the current security status (GOOD, OUTDATED, DUPLICATE, BREACHED) |
hash | string | yes | no | yes | SHA1 hash of the password |
folder | string | yes | no | yes | UUID of the current folder of the password |
revision | string | no | no | yes | UUID of the current revision |
share | string / null | no | no | no | UUID of the share if the password was shared by someone else with the user |
cseType | string | yes | no | yes | Type of the used client side encryption |
sseType | string | no | no | yes | Type of the used server side encryption |
hidden | bool | yes | no | yes | Hides the password in list / find actions |
trashed | bool | no | no | yes | True if the password is in the trash |
favourite | bool | yes | no | yes | True if the user has marked the password as favourite |
editable | bool | no | no | no | Specifies if the encrypted properties can be changed. Might be false for shared passwords |
edited | int | yes | no | yes | Unix timestamp when the user last changed the password |
created | int | no | no | no | Unix timestamp when the password was created |
updated | int | no | no | yes | Unix timestamp when the password was updated |
Level | Description |
---|---|
model | Returns the base model |
+revisions | Adds the revisions property which contains all revisions. A revision consists of all properties marked as versioned and its own created property |
+folder | Fills the folder property with the base model of the folder. If the password is not hidden but the folder is, the base folder will be used |
+tags | Adds the tags property filled with the base model of all tags. Hidden tags are not included in this list if the password is not hidden |
+shares | Adds the shares property filled with the base model of all shares with other users. Fills the share property with the base model of the original share if available |
The properties "revisions", "folder", "tags", "shares" and "share" are also processed if necessary.
Property | Type | Description |
---|---|---|
type | string | Object type, the value is "password" |
icon | string | Url for the default favicon of the website in 32x32px |
preview | string | Url for the default website preview image in 550x350+ px |
created | Date | Date when the password was created |
updated | Date | Date when the password was last updated |
edited | Date | Date when the use last changed the password |
- The status property may be 0 for secure, 1 for weak and 2 for breached.
- The status code GOOD is level 0, OUTDATED and DUPLICATE are level 1 and BREACHED is level 2
- Since the status check is done once per day server side, the DUPLICATE status may take some time to be applied to all affected passwords
- The difference betwenn
updated
andedited
is that updated is always set by the server when the password is changed and edited has to be set by the client.
Action | Url | Method | Description |
---|---|---|---|
list | /api/1.0/password/list |
GET | List all passwords with the default detail level |
list | /api/1.0/password/list |
POST | List all passwords with the given detail level |
show | /api/1.0/password/show |
POST | Show a password |
find | /api/1.0/password/find |
POST | Find passwords matching given criteria |
create | /api/1.0/password/create |
POST | Create a new password |
update | /api/1.0/password/update |
PATCH | Update an existing password |
delete | /api/1.0/password/delete |
DELETE | Delete a password |
restore | /api/1.0/password/restore |
PATCH | Restore an earlier state of a password |
The create action creates a new password with the given attributes.
Argument | Type | Default | Required | Description |
---|---|---|---|---|
password | string | - | yes | The password |
label | string | - | yes | The label of the password |
username | string | empty | no | The username associated with the password |
url | string | empty | no | The url of the associated website |
notes | string | empty | no | The users notes |
customFields | string | empty | no | The custom fields defined by the user |
hash | string | empty | yes | The SHA1 hash of the password |
cseType | string | "none" | no | The client side encryption type |
folder | string | Base folder | no | The current folder of the password |
edited | int | 0 | no | Unix timestamp when the user has last changed the actual password |
hidden | bool | false | no | Whether or not the password should be hidden |
favourite | bool | false | no | Whether or not the user has marked this password as favourite |
tags | array | empty | no | The id of all tags associated with this passwords |
The success status code is 201 Created
Argument | Type | Description |
---|---|---|
id | string | The UUID of the password |
revision | string | The UUID of the revision |
- If the password is not hidden and should be created in a hidden folder, it will be created in the base folder instead
- If the folder uuid is invalid or does not exist, the base folder uuid will be used instead
- If the
edited
argument is "0" or missing, the timestamp from the last revision will be used - If the
edited
time is in the future, the current time will be used - If the
tags
argument contains invalid tag ids, they will be ignored - You can assign hidden tags to a not hidden password, but they will not be visible. Therefore another client might remove the tag by accident
The update action creates a new revision of a password with an updated set of attributes.
Argument | Type | Default | Required | Description |
---|---|---|---|---|
id | string | - | yes | The id of the password object |
password | string | - | yes | The password |
label | string | - | yes | The label of the password |
username | string | empty | no | The username associated with the password |
url | string | empty | no | The url of the associated website |
notes | string | empty | no | The users notes |
customFields | string | empty | no | The custom fields defined by the user |
hash | string | empty | yes | The SHA1 hash of the password |
cseType | string | "none" | no | The client side encryption type |
folder | string | Base folder | no | The current folder of the password |
edited | int | 0 | no | Unix timestamp when the user has last changed the actual password |
hidden | bool | false | no | Whether or not the password should be hidden |
favourite | bool | false | no | Whether or not the user has marked this password as favourite |
tags | array | empty | no | The id of all tags associated with this password |
The success status code is 200 Ok
Argument | Type | Description |
---|---|---|
id | string | The UUID of the password |
revision | string | The UUID of the new revision |
- If the password is not editable any change to the encrypted properties, the cseType and the hash will be ignored.
- If the password is shared you can only use cse types which support sharing
- If the password is shared you can not hide the password
- If the password is not hidden and should be moved to a hidden folder, it will be moved to the base folder instead
- If the password has tags and you want to remove all tags, you need to submit an array with one invalid tag id
- If the folder uuid is invalid or does not exist, the base folder uuid will be used instead
- If the
edited
argument is "0" or missing, the timestamp from the last revision will be used - If the
edited
time is in the future, the current time will be used - If the
tags
argument is empty or missing, no changes will be made - If the
tags
argument contains invalid tag ids, they will be ignored - You can assign hidden tags to a not hidden password, but they will not be visible. Therefore another client might remove the tag by accident
The delete action moves a password to the trash or deletes it completely if it is already in the trash.
Arguments | Type | Default | Required | Description |
---|---|---|---|---|
id | string | - | yes | The id of the password |
The success status code is 200 Ok
Argument | Type | Description |
---|---|---|
id | string | The UUID of the password |
revision | string | The UUID of the new revision. Only if the password was moved to the trash |
- If a password is moved to the trash, the relations to tags will be hidden from the tag, but not the password.
The restore action can restore an earlier state of a password.
Arguments | Type | Default | Required | Description |
---|---|---|---|---|
id | string | - | yes | The id of the password |
revision | string | - | no | The id of the revision |
The success status code is 200 Ok
Argument | Type | Description |
---|---|---|
id | string | The UUID of the password |
revision | string | The UUID of the new revision |
- If no revision is given and the password is in trash, it will be removed from trash
- If no revision is given and the password is not in trash, nothing is done
- If a revision is given and the revision is marked as in trash, it will be removed from trash
- The action may fail if the password is shared but the revision to restore does not meet the requirements for sharing
- This action will always create a new revision
- The server side encryption type may change
- If the folder does not exist anymore, it will be moved to the base folder
- Tag relations can not be restored
- Deleted passwords can not be restored
The show action lists the properties of a single password.
Argument | Type | Default | Required | Description |
---|---|---|---|---|
id | string | - | yes | The id of the password |
detailLevel | string | "model" | no | The detail level of the returned password object |
The success status code is 200 Ok
The return value is a password object with the given detail level
- This is the only action that can access hidden passwords
The list action lists all passwords of the user except those in trash and the hidden ones.
Argument | Type | Default | Required | Description |
---|---|---|---|---|
detailLevel | string | "model" | no | The detail level of the returned password objects |
The success status code is 200 Ok
The return value is a list of password objects with the given detail level
- The list will not include trashed passwords
- The list will not include hidden passwords
- The list will not include suspended passwords where the folder or a parent folder is in the trash
The find action can be used to find all passwords matching the given search criteria. Only a specific set of fields is allowed in the criteria. How the criteria array works is explained on the object search page.
Argument | Type | Default | Required | Description |
---|---|---|---|---|
criteria | array | [] | no | The search criteria |
detailLevel | string | "model" | no | The detail level of the returned password objects |
Field | Type | Description |
---|---|---|
created | int | Unix timestamp when the password was created |
updated | int | Unix timestamp when the password was updated |
edited | int | Unix timestamp when the user last changed the password |
cseType | string | The client side encryption type |
sseType | string | The server side encryption type |
status | int | The server side detected security status |
trashed | bool | Whether or not the password is in the trash |
favourite | bool | Whether or not the user has marked the password as favourite |
The success status code is 200 Ok
The return value is a list of password objects that match the criteria with the given detail level
- The property
trashed
will be set tofalse
if not present - The list will not include hidden passwords
- The list will not include suspended passwords where the folder or a parent folder is in the trash
The custom fields attribute contains a JSON formatted object with user defined custom fields. Custom fields are part of the shared attributes.
Each field has three attributes: the name, the type and the value.
The name
is used as key in the JSON object. This key contains another object with the type
and value
keys.
If the name starts with an underscore, the field will be visually hidden and not displayed in the ui.
{
"Field Name": {
"type": "text",
"value": "Field Value"
},
"_HiddenField": {
"type": "text",
"value": "Field Value"
}
}
Type | Description |
---|---|
text | Generic text value |
secret | A secret value which should be treated like a password |
An email address | |
url | A valid full url. Any protocol is allowed |
file | The path to a file accessible over WebDav. The base url of the WebDav service is defined in the setting server.baseUrl.webdav . |
- Only 20 fields per password are allowed including hidden fields
- The name has a maximum length of 48 characters
- The value has a maximum length of 320 characters
- The total length of all custom fields can not exceed 8192 characters
- The value should not be but may be empty