Skip to main content
API docs by Redocly

Passbolt API (5.0.0)

Download OpenAPI specification:Download

E-mail: [email protected] License: AGPL-3.0 Terms of Service

This is a low-level overview of the API and its endpoints, if you need higher-level guides for interacting with the endpoints, use the Developer guide.

This reference grows with the product: endpoint groups are added as they are described, so an endpoint you do not find here may still exist on your instance. The route configuration of your server is what tells you exactly what it exposes.

Action logs

Read the activity of an entity, or the raw action log. Requires the Pro Edition, the Enterprise Edition or a Cloud plan.

Get the activity of a folder.

Returns the interpreted activities recorded for a folder. The caller must have access to the folder: a folder that does not exist and a folder the caller cannot see are answered the same way. This route is only registered when the folders plugin is enabled, and an instance without it answers the same 404, so the two cases cannot be told apart from the response.

Authorizations:
bearerHttpAuthentication
path Parameters
folderId
required
string <uuid>

ID for the folder being manipulated.

query Parameters
limit
integer

Maximum number of elements to return on one page.

page
integer

Page of results to return, starting at 1.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/actionlog/folder/e97b14ba-8957-57c9-a357-f78a6e1e1a46.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": []
}

Get the raw action log.

Returns the raw log entries recorded by the action log plugin, rather than the interpreted activities of an entity. Reserved to administrators.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[has-users]
Array of strings <uuid> [ items <uuid > ]

Only return elements filtered by users.

filter[is-success]
boolean

Only return success elements.

filter[created-after]
string

Only return elements created after a specific date-time.

filter[created-before]
string

Only return elements created before a specific date-time.

limit
integer

Maximum number of elements to return on one page.

page
integer

Page of results to return, starting at 1.

Responses

Request samples 

curl --request GET \
  --url '{{API_BASE_URL}}/actionlog/logs.json?limit=50' \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get the activity of a resource.

Returns the interpreted activities recorded for a resource. The caller must have access to the resource: a resource that does not exist and a resource the caller cannot see are answered the same way.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

query Parameters
limit
integer

Maximum number of elements to return on one page.

page
integer

Page of results to return, starting at 1.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/actionlog/resource/8e3874ae-4b40-590b-968a-418f704b9d9a.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get the activity of a user.

Returns the interpreted activities recorded for a user account.

Authorizations:
bearerHttpAuthentication
path Parameters
userId
required
string <uuid>

ID for the user being manipulated. Can be set to me when viewing a user.

query Parameters
limit
integer

Maximum number of elements to return on one page.

page
integer

Page of results to return, starting at 1.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/actionlog/user/f848277c-5398-58f8-a82a-72397af2d450.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Authentication (GPGAuth)

The legacy authentication method, using the GPGAuth protocol.

Find more here.

Check authentication status.

Can be used as a session keep-alive.

Authorizations:
gpgCookieAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/auth/is-authenticated.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Log in.

Request Body schema: application/json
required

The user's key fingerprint and challenge data when required.

required
object
required
object
keyid
required
string
server_verify_token
string

Used for server key verification.

user_token_result
string

Used for client key verification.

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Log out.

Authorizations:
gpgCookieAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/auth/logout.json

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Get the server's public PGP key.

Can be used to validate data signature.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/auth/verify.json

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Verify the server's identity.

Request Body schema: application/json
required

The user's key fingerprint and an encrypted challenge token.

required
object
required
object
keyid
required
string
server_verify_token
string

Used for server key verification.

user_token_result
string

Used for client key verification.

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Authentication (JWT)

JWT-based authentication is the preferred way to interact with the Passbolt API. Find more here

Get the JWKs server information.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/auth/jwt/jwks.json

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Login.

Request Body schema: application/json
required

The user and refresh token for session identification.

user_id
required
string <uuid>
challenge
required
string

gpg_encrypt(gpg_sign(challenge_message, user_key), server_key)

Responses

Request samples

Content type
application/json
{
  • "user_id": "8bb80df5-700c-48ce-b568-85a60fc3c8f2",
  • "challenge": "-----BEGIN PGP MESSAGE-----"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Logout.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The session associated to the refresh token you want to revoke.

refresh_token
string <uuid>

Responses

Request samples

Content type
application/json
Example
{
  • "refresh_token": "ad71952e-7842-599e-a19e-3a82e6974b23"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Refresh access token.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The user and refresh token for session identification.

refresh_token
required
string <uuid>
user_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "user_id": "8bb80df5-700c-48ce-b568-85a60fc3c8f2",
  • "refresh_token": "f8cea352-6bd3-4944-9523-20b31272bef0"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Get the JWT RSA server information.

This is not the key to use when encrypting the JWT login challenge.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/auth/jwt/rsa.json

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Avatars

Query avatar images.

Get an avatar as an image.

When the avatar doesn't exist, a placeholder image is returned instead.

path Parameters
avatarId
required
string <uuid>

ID for the avatar being manipulated.

avatarFormat
required
string
Enum: "medium.jpg" "small.jpg"

Format for the avatar being manipulated.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/avatars/view/8ef95b32-e2a3-4b58-827c-dd67e68cfb49/medium.jpg

Comments

Manipulate comments for resources.

Update a comment.

Authorizations:
bearerHttpAuthentication
path Parameters
commentId
required
string <uuid>

ID for the comment being manipulated.

Request Body schema: application/json
required

The comment you want to update

content
required
string

Responses

Request samples

Content type
application/json
{
  • "content": "no comment"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Delete a comment.

Authorizations:
bearerHttpAuthentication
path Parameters
commentId
required
string <uuid>

ID for the comment being manipulated.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/comments/9149d7d7-e191-41d5-a263-cfccbd775f0b.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Get comments for a resource.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

query Parameters
contain[creator]
integer
Enum: 1 0

Add creator to response body.

contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Add a comment.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

Request Body schema: application/json
required

The comment you want to add

content
required
string
parent_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "content": "no comment"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Directory Sync

Run directory synchronization.

Simulate directory synchronization without making changes.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/directorysync/synchronize/dry-run.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    },
  • "groups": [ ]
}

Run the directory synchronization.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request POST \
  --url {{API_BASE_URL}}/directorysync/synchronize.json.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}' \

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    },
  • "groups": [ ]
}

Favorites

The favorite endpoints are used to add or remove a Resource from your favorites.

Unset a resource as favorite.

Authorizations:
bearerHttpAuthentication
path Parameters
favoriteId
required
string <uuid>

ID for the favorite being manipulated.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/favorites/9edeffa4-a4fb-4e6a-b5f8-1ffc3f408335.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Set a resource as favorite.

Authorizations:
bearerHttpAuthentication
path Parameters
foreignId
required
string <uuid>

ID for the foreign element being manipulated.

Responses

Request samples 

curl --request POST \
  --url {{API_BASE_URL}}/favorites/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'
  --header 'Content-Type: application/json' \

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Folders

Organize your passwords and share them in bulk using folders.

Get multiple folders.

Authorizations:
bearerHttpAuthentication
query Parameters
contain[children_resources]
integer
Enum: 1 0

Add children resources to response body.

contain[children_folders]
integer
Enum: 1 0

Add children folders to response body.

contain[creator]
integer
Enum: 1 0

Add creator to response body.

contain[creator.profile]
integer
Enum: 1 0

Add creator and their profile to response body.

contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[modifier.profile]
integer
Enum: 1 0

Add modifier and their profile to response body.

contain[permission]
integer
Enum: 1 0

Add permission to response body.

contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

contain[permissions.user.profile]
integer
Enum: 1 0

Add user profile to permissions in response body.

contain[permissions.group]
integer
Enum: 1 0

Add group to permissions in response body.

filter[has-id]
string <uuid>

Only return elements filtered by their id.

filter[has-parent]
string <uuid>

Only return elements filtered by parent folder.

filter[search]
string

Filter using a keyword or a string.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/folders.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Create a folder.

Encrypted metadata for this item is not supported on all clients.

Authorizations:
bearerHttpAuthentication
query Parameters
contain[children_resources]
integer
Enum: 1 0

Add children resources to response body.

contain[children_folders]
integer
Enum: 1 0

Add children folders to response body.

contain[creator]
integer
Enum: 1 0

Add creator to response body.

contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[permission]
integer
Enum: 1 0

Add permission to response body.

contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

contain[permissions.user.profile]
integer
Enum: 1 0

Add user profile to permissions in response body.

contain[permissions.group]
integer
Enum: 1 0

Add group to permissions in response body.

Request Body schema: application/json
required

The folder you want to create

metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"

Responses

Request samples

Content type
application/json
Example
{
  • "metadata": "-----BEGIN PGP MESSAGE-----",
  • "metadata_key_id": "e3dabc04-cfbd-45c1-9f7d-827c61603e20",
  • "metadata_key_type": "shared_key"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Get a folder.

Authorizations:
bearerHttpAuthentication
path Parameters
folderId
required
string <uuid>

ID for the folder being manipulated.

query Parameters
contain[children_resources]
integer
Enum: 1 0

Add children resources to response body.

contain[children_folders]
integer
Enum: 1 0

Add children folders to response body.

contain[creator]
integer
Enum: 1 0

Add creator to response body.

contain[creator.profile]
integer
Enum: 1 0

Add creator and their profile to response body.

contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[modifier.profile]
integer
Enum: 1 0

Add modifier and their profile to response body.

contain[permission]
integer
Enum: 1 0

Add permission to response body.

contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

contain[permissions.user.profile]
integer
Enum: 1 0

Add user profile to permissions in response body.

contain[permissions.group]
integer
Enum: 1 0

Add group to permissions in response body.

filter[has-id]
string <uuid>

Only return elements filtered by their id.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/folders/27605bac-8aa8-4fe4-a80b-486d8b76c748.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Update a folder.

Encrypted metadata for this item is not supported on all clients.

The current user must have the “update” or “owner” permission on the folder.

Authorizations:
bearerHttpAuthentication
path Parameters
folderId
required
string <uuid>

ID for the folder being manipulated.

query Parameters
contain[children_resources]
integer
Enum: 1 0

Add children resources to response body.

contain[children_folders]
integer
Enum: 1 0

Add children folders to response body.

contain[creator]
integer
Enum: 1 0

Add creator to response body.

contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[permission]
integer
Enum: 1 0

Add permission to response body.

contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

contain[permissions.user.profile]
integer
Enum: 1 0

Add user profile to permissions in response body.

contain[permissions.group]
integer
Enum: 1 0

Add group to permissions in response body.

Request Body schema: application/json
required

The folder you want to update

metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"

Responses

Request samples

Content type
application/json
{
  • "metadata": "----BEGIN PGP MESSAGE-----",
  • "metadata_key_id": "9d9a6672-35d6-4d0f-a807-b90edf25c275",
  • "metadata_key_type": "shared_key"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Delete a folder.

Authorizations:
bearerHttpAuthentication
path Parameters
folderId
required
string <uuid>

ID for the folder being manipulated.

query Parameters
cascade
integer
Enum: 1 0

Delete element and its children elements.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/folders/b2a72cb2-508c-43ad-b96f-697f7ad21635.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

GPG keys

In order to encrypt information, the server and the clients needs the user's public keys. These OpenPGP endpoints let you query the saved public key data.

Get multiple GPG keys.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[modified-after]
string

Only return elements modified after a timestamp.

filter[is-deleted]
integer
Enum: 1 0

Only return deleted elements.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/gpgkeys.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get a GPG key.

Authorizations:
bearerHttpAuthentication
path Parameters
gpgkeyId
required
string <uuid>

ID for the GPG key being manipulated.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/gpgkeys/ed4d9ea6-f354-4a74-ad09-4e1dd69041ec.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Groups

Organize users in logical groups to make it easier to share resources with them.

Get multiple groups.

Authorizations:
bearerHttpAuthentication
query Parameters
contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[modifier.profile]
integer
Enum: 1 0

Add modifier and their profile to response body.

contain[my_group_user]
integer
Enum: 1 0

Add my_group_user to groups in response body.

contain[groups_users]
integer
Enum: 1 0

Add group users to groups in response body.

contain[groups_users.user]
integer
Enum: 1 0

Add group users' user data to groups in response body.

contain[groups_users.user.profile]
integer
Enum: 1 0

Add group users' user profiles to groups in response body.

contain[groups_users.user.gpgkey]
integer
Enum: 1 0

Add group users' user gpg key to groups in response body.

filter[has-users]
Array of strings <uuid> [ items <uuid > ]

Only return elements filtered by users.

filter[has-managers]
Array of strings <uuid> [ items <uuid > ]

Only return elements filtered by managers.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/groups.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
Example
{
  • "header": {
    },
  • "body": [
    ]
}

Create a group.

Please note that only users with Admin role can create a group.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The group you want to create

name
required
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "Groupe B",
  • "groups_users": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Get a group.

Authorizations:
bearerHttpAuthentication
path Parameters
groupId
required
string <uuid>

ID for the group being manipulated.

query Parameters
contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[modifier.profile]
integer
Enum: 1 0

Add modifier and their profile to response body.

contain[users]
integer
Enum: 1 0

Add users to response body.

contain[my_group_user]
integer
Enum: 1 0

Add my_group_user to groups in response body.

contain[groups_users]
integer
Enum: 1 0

Add group users to groups in response body.

contain[groups_users.user]
integer
Enum: 1 0

Add group users' user data to groups in response body.

contain[groups_users.user.profile]
integer
Enum: 1 0

Add group users' user profiles to groups in response body.

contain[groups_users.user.gpgkey]
integer
Enum: 1 0

Add group users' user gpg key to groups in response body.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/groups/8a3c5c4e-e931-4e6b-854a-9b2e9afcd3bc.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
Example
{
  • "header": {
    },
  • "body": {
    }
}

Update a group.

Authorizations:
bearerHttpAuthentication
path Parameters
groupId
required
string <uuid>

ID for the group being manipulated.

Request Body schema: application/json
required

The group you want to update

name
required
string
required
Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "WRC",
  • "groups_users": [
    ],
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Delete a group.

Only a group manager or a user with administrator role can delete a group. A group cannot be deleted as long as it is the sole owner of a shared resource or folder.

Authorizations:
bearerHttpAuthentication
path Parameters
groupId
required
string <uuid>

ID for the group being manipulated.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/groups/164d51b8-d6ce-4d59-b8a0-43869919407e.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Dry run a group update.

Authorizations:
bearerHttpAuthentication
path Parameters
groupId
required
string <uuid>

ID for the group being manipulated.

Request Body schema: application/json
required

The group you want to update

name
required
string
required
Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "WRC",
  • "groups_users": [
    ],
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Dry run a group deletion.

Authorizations:
bearerHttpAuthentication
path Parameters
groupId
required
string <uuid>

ID for the group being manipulated.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/groups/164d51b8-d6ce-4d59-b8a0-43869919407e/dry-run.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [ ]
}

Healthcheck

Gather data about the passbolt instance's health.

Get healthcheck information.

Only administrators can query this endpoint.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/healthcheck.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Check if passbolt is up.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/healthcheck/status.json

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": "OK"
}

Metadata keys

Manipulate metadata keys.

Get metadata keys.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[deleted]
integer
Enum: 1 0

Filter for deleted elements.

filter[expired]
integer
Enum: 1 0

Filter for expired elements.

contain[metadata_private_keys]
integer
Enum: 1 0

Add metadata private keys in response.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/keys.json \
  --header 'authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Create a metadata key.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The metadata key you want to create

armored_key
required
string
fingerprint
required
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "fingerprint": "17B5913BC13128674F2A6F31C79A1AB152C3C573",
  • "armored_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----",
  • "metadata_private_keys": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Mark a metadata key as expired.

Authorizations:
bearerHttpAuthentication
path Parameters
metadataKeyId
required
string <uuid>

The metadata key identifier being manipulated.

Request Body schema: application/json
required

The metadata key you want to update

fingerprint
required
string
armored_key
required
string
expired
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "fingerprint": "17B5913BC13128674F2A6F31C79A1AB152C3C573",
  • "armored_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----",
  • "expired": "2025-02-25T09:00:00+00:00"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Delete a metadata key.

Authorizations:
bearerHttpAuthentication
path Parameters
metadataKeyId
required
string <uuid>

The metadata key identifier being manipulated.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/metadata/keys/6c598bc2-8354-4d47-8844-37bae9fed02f.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Get metadata keys settings.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/keys/settings.json \
  --header 'authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Update metadata keys settings.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The metadata key settings you want to update

allow_usage_of_personal_keys
required
boolean
zero_knowledge_key_share
required
boolean
Array of objects

Responses

Request samples

Content type
application/json
{
  • "allow_usage_of_personal_keys": true,
  • "zero_knowledge_key_share": false
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Metadata private keys

Manipulate private keys for metadata.

Create a metadata private key.

Can also be used for sharing a missing private key for one or more users.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The metadata private keys that you want to create.

Array
data
required
string
user_id
required
string <uuid>
metadata_key_id
required
string <uuid>

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": { }
}

Update a metadata private key.

Authorizations:
bearerHttpAuthentication
path Parameters
metadataPrivateKeyId
required
string <uuid>

ID for the metadata private key manipulated.

Request Body schema: application/json
required

The metadata private keys that you want to update.

data
required
string

Responses

Request samples

Content type
application/json
{
  • "data": "-----BEGIN PGP MESSAGE-----"
}

Response samples

Content type
application/json
{
  • "user_id": "eca7c94a-02ac-4e08-a7e1-035981c34868",
  • "data": "-----BEGIN PGP MESSAGE-----",
  • "created_by": "eca7c94a-02ac-4e08-a7e1-035981c34868",
  • "modified_by": "4448fee0-2eef-4d47-b221-2101317f60d1"
}

Metadata types settings

Retrieve information about the resource types settings selected by the administrators

Get metadata types settings

Get information from the resource types settings, as selected by the administrators.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/types/settings.json \
  --header 'authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Upgrade a resource types settings

Administrators can define which resource type is the default

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The metadata types settings you want to update

default_resource_types
required
string
Enum: "v4" "v5"
default_folder_type
required
string
Enum: "v4" "v5"
default_tag_type
required
string
Enum: "v4" "v5"
default_comment_type
required
string
Enum: "v4" "v5"
allow_creation_of_v5_resources
required
boolean
allow_creation_of_v5_folders
required
boolean
allow_creation_of_v5_tags
required
boolean
allow_creation_of_v5_comments
required
boolean
allow_creation_of_v4_resources
required
boolean
allow_creation_of_v4_folders
required
boolean
allow_creation_of_v4_tags
required
boolean
allow_creation_of_v4_comments
required
boolean
allow_v5_v4_downgrade
required
boolean
allow_v4_v5_upgrade
required
boolean

Responses

Request samples

Content type
application/json
{
  • "default_resource_types": "v5",
  • "default_folder_type": "v4",
  • "default_tag_type": "v4",
  • "default_comment_type": "v4",
  • "allow_creation_of_v5_resources": true,
  • "allow_creation_of_v5_folders": false,
  • "allow_creation_of_v5_tags": false,
  • "allow_creation_of_v5_comments": false,
  • "allow_creation_of_v4_resources": true,
  • "allow_creation_of_v4_folders": true,
  • "allow_creation_of_v4_tags": true,
  • "allow_creation_of_v4_comments": true,
  • "allow_v5_v4_downgrade": false,
  • "allow_v4_v5_upgrade": true
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Metadata rotate key

Gather information about metadata keys that needs to be rotated

Get folders with expired keys

See the folders that are using an expired key that needs to/can be rotated. Only administrators can query this endpoint.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/rotate-key/{{MODEL}}.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Rotate expired metadata keys for folders

Rotate the metadata of a given set of folders

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The object you want to rotate the metadata key

Array
metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
id
required
string <uuid>
modified
required
string <date-time>
modified_by
required
string <uuid>

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get resources with expired keys

See the resources that are using an expired key that needs to/can be rotated. Only administrators can query this endpoint.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/rotate-key/{{MODEL}}.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Rotate expired metadata keys for resources

Rotate the metadata of a given set of resources

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The object you want to rotate the metadata key

Array
metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
id
required
string <uuid>
modified
required
string <date-time>
modified_by
required
string <uuid>

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get tags with expired keys

This endpoint is available since version 5.1.

See the tags that are using an expired key that needs to/can be rotated. Only administrators can query this endpoint.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/rotate-key/{{MODEL}}.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Rotate expired metadata keys for tags

This endpoint is available since version 5.1.

Rotate the metadata key of a given set of tags.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The tags you want to rotate the metadata key

Array
metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
id
required
string <uuid>

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Metadata session key

Gather information on the saved encrypted session keys cache

Get session keys.

Get a list of available encrypted session keys in cache for the given user.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/session-keys.json \
  --header 'authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Add a session key.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The metadata session key you want to add

data
required
string

Responses

Request samples

Content type
application/json
{
  • "data": "-----BEGIN PGP MESSAGE-----"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Update a given session-key entry.

Authorizations:
bearerHttpAuthentication
path Parameters
sessionKeyId
required
string <uuid>

ID for the session key being manipulated

Request Body schema: application/json
required

The metadata session key you want to update

data
required
string
modified
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "data": "----BEGIN PGP MESSAGE-----",
  • "modified": "2025-02-18T15:52:17+00:00"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Delete a given session-key entry.

Authorizations:
bearerHttpAuthentication
path Parameters
sessionKeyId
required
string <uuid>

ID for the session key being manipulated

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/metadata/session-keys/9edeffa4-a4fb-4e6a-b5f8-1ffc3f408335.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Metadata upgrade

Upgrading elements to the new v5 metadata format

Get Upgradable Folders

Encrypted metadata for this item is not supported on all clients.

Retrieves a list of folders that are eligible for an upgrade to v5 format. Results are paginated and the page size is fixed at 20.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[is-shared]
boolean

Only return shared items.

contain[permission]
integer
Enum: 1 0

Add permission to response body.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/upgrade/folders.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Upgrade a folder

Encrypted metadata for this item is not supported on all clients.

Upgrade folders that are eligible for an upgrade to v5 format.

Authorizations:
bearerHttpAuthentication
query Parameters
contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

Request Body schema: application/json
required

The folders you want to upgrade the metadata for to v5 format

Array
metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
id
required
string <uuid>
modified
required
string <date-time>
modified_by
required
string <uuid>

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get Upgradable Resources

Retrieves a list of resources that are eligible for an upgrade to v5 format. Results are paginated and the page size is fixed at 20.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[is-shared]
boolean

Only return shared items.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/upgrade/resources.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Upgrade a Resource

Upgrade resources that are eligible for an upgrade to v5 format.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[is-shared]
boolean

Only return shared items.

contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

Request Body schema: application/json
required

The resources you want to upgrade the metadata for to v5 format

Array
metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
id
required
string <uuid>
modified
required
string <date-time>
modified_by
required
string <uuid>

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get Upgradable Tags

This endpoint is available since version 5.1.

Encrypted metadata for this item is not supported on all clients.

Retrieves a list of tags that are eligible for an upgrade to v5 format. Results are paginated and the page size is fixed at 20.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[is-shared]
boolean

Only return shared items.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/metadata/upgrade/tags.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Upgrade a tag

This endpoint is available since version 5.1.

Encrypted metadata for this item is not supported on all clients.

Upgrade tags that are eligible for an upgrade to v5 format.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[is-shared]
boolean

Only return shared items.

Request Body schema: application/json
required

The tags you want to upgrade the metadata for to v5 format

Array
metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
id
required
string <uuid>
is_shared
required
boolean

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Move

Move a folder or a resource across folders.

Move an element.

Authorizations:
bearerHttpAuthentication
path Parameters
foreignModel
required
string
Enum: "resource" "folder"

Type for the foreign model being moved.

foreignId
required
string <uuid>

ID for the foreign element being manipulated.

Request Body schema: application/json
required

The target parent folder ID

folder_parent_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "folder_parent_id": "a55d29ee-6781-49d6-b11e-36589d258be8"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Multi-Factor Authentication

Complete and validate authentication for users with MFA enabled.

Check multi-factor authentication.

Check if MFA validation is needed. 400 means that this kind of MFA is not required.

Authorizations:
bearerHttpAuthentication
path Parameters
mfaProviderName
string
Enum: "totp" "yubikey" "duo"

Name for the MFA provider.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/mfa/verify/totp.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Attempt multi-factor authentication.

Authorizations:
bearerHttpAuthentication
path Parameters
mfaProviderName
string
Enum: "totp" "yubikey" "duo"

Name for the MFA provider.

Request Body schema: application/json
required

The code for the MFA attempt.

Any of
totp
required
string

One-time code for TOTP-based MFA.

remember
integer
Enum: 0 1

Responses

Request samples

Content type
application/json
{
  • "totp": "635742"
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Information about MFA requirements.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/mfa/verify/error.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": ""
}

Permissions

Query permissions for resources.

Get permissions for a resource.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

query Parameters
contain[group]
integer
Enum: 1 0

Add group to response body.

contain[user]
integer
Enum: 1 0

Add user to response body.

contain[user.profile]
integer
Enum: 1 0

Add user profile to user data in response body.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/permissions/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Resources

A resource holds the metadata for its secrets.

Get multiple resources.

Authorizations:
bearerHttpAuthentication
query Parameters
contain[creator]
integer
Enum: 1 0

Add creator to response body.

contain[favorite]
integer
Enum: 1 0

Add favorite to response body.

contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[secret]
integer
Enum: 1 0

Add secrets to response body.

contain[resource-type]
integer
Enum: 1 0

Add resource type to response body.

contain[permission]
integer
Enum: 1 0

Add permission to response body.

contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

contain[permissions.user.profile]
integer
Enum: 1 0

Add user profile to permissions in response body.

contain[permissions.group]
integer
Enum: 1 0

Add group to permissions in response body.

filter[is-favorite]
boolean

Only return favorite elements.

filter[is-shared-with-group]
string <uuid>

Only return elements shared with group.

filter[is-owned-by-me]
boolean

Only return elements owned by yourself.

filter[is-shared-with-me]
boolean

Only return elements shared to yourself and you are not owner.

filter[has-id]
string <uuid>

Only return elements filtered by their id.

filter[has-parent]
string <uuid>

Only return elements filtered by parent folder.

filter[metadata_key_type]
string <uuid>

Only return elements that match the metadata key type

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/resources.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
Example
{
  • "header": {
    },
  • "body": [
    ]
}

Create a resource.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The resource you want to create or update

metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
expired
required
string or null <date-time>
folder_parent_id
required
string or null <uuid>
resource_type_id
required
string <uuid>
required
Array of objects

One entry per recipient. The data of each entry is an armoured OpenPGP message whose cleartext is the secret of the resource. Its shape depends on the resource type: a JSON object carrying object_type set to PASSBOLT_SECRET_DATA for every v5 type but v5-password-string, which encrypts the password as a bare string. The fields expected for each type are listed in the guide on working with v5 encrypted metadata.

Responses

Request samples

Content type
application/json
{
  • "folder_parent_id": null,
  • "personal": true,
  • "expired": null,
  • "metadata_key_id": "9d9a6672-35d6-4d0f-a807-b90edf25c275",
  • "resource_type_id": "dd1f723d-0d1e-513f-8218-4055dc0530d0",
  • "metadata_key_type": "shared_key",
  • "metadata": "-----BEGIN PGP MESSAGE-----",
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ae60d89c-f13b-4fb1-b2dc-c8dc806cac88",
  • "metadata": "-----BEGIN PGP MESSAGE-----",
  • "metadata_key_id": "0194fec1-65fa-7b6f-935a-9541c1c13281",
  • "metadata_key_type": "shared_key",
  • "deleted": false,
  • "created": "2024-07-08T08:06:25+00:00",
  • "modified": "2024-07-08T08:06:25+00:00",
  • "created_by": "8bb80df5-700c-48ce-b568-85a60fc3c8f2",
  • "modified_by": "8bb80df5-700c-48ce-b568-85a60fc3c8f2",
  • "resource_type_id": "a28a04cd-6f53-518a-967c-9963bf9cec51",
  • "expired": null,
  • "folder_parent_id": null,
  • "personal": true
}

Get a resource.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

query Parameters
contain[creator]
integer
Enum: 1 0

Add creator to response body.

contain[favorite]
integer
Enum: 1 0

Add favorite to response body.

contain[modifier]
integer
Enum: 1 0

Add modifier to response body.

contain[secret]
integer
Enum: 1 0

Add secrets to response body.

contain[resource-type]
integer
Enum: 1 0

Add resource type to response body.

contain[permission]
integer
Enum: 1 0

Add permission to response body.

contain[permissions]
integer
Enum: 1 0

Add permissions to response body.

contain[permissions.user.profile]
integer
Enum: 1 0

Add user profile to permissions in response body.

contain[permissions.group]
integer
Enum: 1 0

Add group to permissions in response body.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/resources/ae60d89c-f13b-4fb1-b2dc-c8dc806cac88.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
Example
{
  • "header": {
    },
  • "body": {
    }
}

Update a resource.

If the password you are updating has been shared with 7 users, the secrets key will need to be an array of 7 objects.

You must encrypt and sign the new plaintext passwords using the recipient public key and the current user secret key. You can then create a list which include one object per user: the data key holds the encrypted plaintext password and user_id holds the user UUID.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

Request Body schema: application/json
required

The resource you want to create or update

metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
expired
required
string or null <date-time>
folder_parent_id
required
string or null <uuid>
resource_type_id
required
string <uuid>
required
Array of objects

One entry per recipient. The data of each entry is an armoured OpenPGP message whose cleartext is the secret of the resource. Its shape depends on the resource type: a JSON object carrying object_type set to PASSBOLT_SECRET_DATA for every v5 type but v5-password-string, which encrypts the password as a bare string. The fields expected for each type are listed in the guide on working with v5 encrypted metadata.

Responses

Request samples

Content type
application/json
{
  • "folder_parent_id": null,
  • "personal": true,
  • "expired": null,
  • "metadata_key_id": "9d9a6672-35d6-4d0f-a807-b90edf25c275",
  • "resource_type_id": "dd1f723d-0d1e-513f-8218-4055dc0530d0",
  • "metadata_key_type": "shared_key",
  • "metadata": "-----BEGIN PGP MESSAGE-----",
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ae60d89c-f13b-4fb1-b2dc-c8dc806cac88",
  • "metadata": "-----BEGIN PGP MESSAGE-----",
  • "metadata_key_id": "0194fec1-65fa-7b6f-935a-9541c1c13281",
  • "metadata_key_type": "shared_key",
  • "deleted": false,
  • "created": "2024-07-08T08:06:25+00:00",
  • "modified": "2024-07-08T08:06:25+00:00",
  • "created_by": "8bb80df5-700c-48ce-b568-85a60fc3c8f2",
  • "modified_by": "8bb80df5-700c-48ce-b568-85a60fc3c8f2",
  • "resource_type_id": "a28a04cd-6f53-518a-967c-9963bf9cec51",
  • "expired": null,
  • "folder_parent_id": null,
  • "personal": true
}

Delete a resource.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/resources/43051c9f-7122-4887-81e8-3b390cf0f04a.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Resource types

Resource-types are used for describing how and what data is stored for a resource and its associated secrets.

Get multiple resource types.

Authorizations:
bearerHttpAuthentication
query Parameters
contain[resources_count]
integer
Enum: 1 0

Get the number of count of resources associated to this type of resource.

filter[is-deleted]
integer
Enum: 1 0

Only return deleted elements.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/resource-types.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Get a resource type.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceTypeId
required
string <uuid>

ID for the resource type being manipulated.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/resource-types/43051c9f-7122-4887-81e8-3b390cf0f04a.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Delete a resource type.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceTypeId
required
string <uuid>

ID for the resource type being manipulated.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/resource-types/43051c9f-7122-4887-81e8-3b390cf0f04a.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Update resource type.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceTypeId
required
string <uuid>

ID for the resource type being manipulated.

Request Body schema: application/json
required

The resource types you want to update

deleted
boolean or null

Responses

Request samples

Content type
application/json
{
  • "deleted": null
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": ""
}

Roles

Different categories of users.

Get multiple roles.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/roles.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Secrets

Secrets associated to resources.

View user's secret for a resource.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceId
required
string <uuid>

ID for the resource being manipulated.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/secrets/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Settings

Retrieve the server settings

Get the server settings.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
--url {{API_BASE_URL}}/settings.json

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Shares

Share resources and folders to users with an exhaustive permission system.

Share a resource.

Authorizations:
bearerHttpAuthentication
path Parameters
foreignId
required
string <uuid>

ID for the foreign element being manipulated.

Request Body schema: application/json
required

The permissions you want to apply

Array of objects
Array of objects

Not required on simulation.

Responses

Request samples

Content type
application/json
Example
{
  • "permissions": [
    ],
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Share a folder.

Requires the Folders plugin. This endpoint also accepts the POST method.

Authorizations:
bearerHttpAuthentication
path Parameters
foreignId
required
string <uuid>

ID for the foreign element being manipulated.

Request Body schema: application/json
required

The permissions you want to apply

Array of objects
Array of objects

Not required on simulation.

Responses

Request samples

Content type
application/json
Example
{
  • "permissions": [
    ],
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Get AROs for sharing.

Authorizations:
bearerHttpAuthentication
query Parameters
filter[search]
string

Filter using a keyword or a string.

contain[groups_users]
integer
Enum: 1 0

Add group users to groups in response body.

contain[gpgkey]
integer
Enum: 1 0

Add GPG key data to response body.

contain[role]
integer
Enum: 1 0

Add role to response body.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/share/search-aros.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Simulate sharing a resource.

Authorizations:
bearerHttpAuthentication
path Parameters
foreignId
required
string <uuid>

ID for the foreign element being manipulated.

Request Body schema: application/json
required

The permissions you want to apply

Array of objects
Array of objects

Not required on simulation.

Responses

Request samples

Content type
application/json
{
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Tags

Get tags and add tags to resources to categorize them.

Get personal tags and shared tags.

Encrypted metadata for tags is available since version 5.1, and is not supported on all clients.

Authorizations:
bearerHttpAuthentication

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/tags.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Update a tag.

Encrypted metadata for tags is available since version 5.1, and is not supported on all clients.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceOrTagId
required
string <uuid>

The tag (for PUT) or resource (for POST) identifier being manipulated.

Request Body schema: application/json
required

The tag to update.

metadata
required
string

An armoured OpenPGP message. Its cleartext is a JSON object carrying an object_type field that names the payload, PASSBOLT_RESOURCE_METADATA for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata.

metadata_key_id
required
string <uuid>
metadata_key_type
required
string
Enum: "user_key" "shared_key"
is_shared
required
boolean

Responses

Request samples

Content type
application/json
{
  • "metadata": "-----BEGIN PGP MESSAGE-----",
  • "metadata_key_id": "ed94010c-6a97-488c-a60c-cfc6558f3ed7",
  • "metadata_key_type": "shared_key",
  • "is_shared": false
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Add tags to a resource.

Encrypted metadata for tags is available since version 5.1, and is not supported on all clients.

Authorizations:
bearerHttpAuthentication
path Parameters
resourceOrTagId
required
string <uuid>

The tag (for PUT) or resource (for POST) identifier being manipulated.

Request Body schema: application/json
required

The tags to set for the resource.

Any of
id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Users

User are entities with the ability to interact with the application.

Get multiple users.

Authorizations:
bearerHttpAuthentication
query Parameters
contain[last_logged_in]
integer
Enum: 1 0

Add last logged in to response body.

contain[groups_users]
integer
Enum: 1 0

Add group users to groups in response body.

contain[gpgkey]
integer
Enum: 1 0

Add GPG key data to response body.

contain[profile]
integer
Enum: 1 0

Add profile to response body.

contain[role]
integer
Enum: 1 0

Add role to response body.

contain[missing_metadata_key_ids]
integer
Enum: 1 0

Add missing metadata key IDs to response body.

filter[search]
string

Filter using a keyword or a string.

filter[has-groups]
Array of strings <uuid> [ items <uuid > ]

Only return elements filtered by groups.

filter[has-access]
Array of strings <uuid> [ items <uuid > ]

Only return elements where specified users have access.

filter[is-admin]
boolean

Only return admin users.

filter[is-active]
boolean

Only return active elements.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/users.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": [
    ]
}

Create a user.

Only users with admin role can create other users.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
required

The user you want to create

username
required
string <email>
role_id
string <uuid>
required
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Get a user.

Authorizations:
bearerHttpAuthentication
path Parameters
userId
required
string <uuid>

ID for the user being manipulated. Can be set to me when viewing a user.

query Parameters
contain[missing_metadata_key_ids]
integer
Enum: 1 0

Add missing metadata key IDs to response body.

Responses

Request samples 

curl --request GET \
  --url {{API_BASE_URL}}/users/8c640fd5-268c-4ae0-9e35-2f120cf1a831.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Update a user.

Neither the email or the username field which can be updated, and only administrators can update a user's role.

Authorizations:
bearerHttpAuthentication
path Parameters
userId
required
string <uuid>

ID for the user being manipulated. Can be set to me when viewing a user.

Request Body schema: application/json
required

The user you want to update

role_id
string <uuid>
disabled
boolean
object

Responses

Request samples

Content type
application/json
{
  • "profile": {
    }
}

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": {
    }
}

Delete a user.

Only a user with an administrator role can delete users. A user can not be deleted as long as:

  • They are the sole owner of a shared resource.
  • They are a manager of a non empty group.

In this case you will need to transfer the ownership of the shared resources and appoint a new manager to the group in order to proceed.

Authorizations:
bearerHttpAuthentication
path Parameters
userId
required
string <uuid>

ID for the user being manipulated. Can be set to me when viewing a user.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/users/8c640fd5-268c-4ae0-9e35-2f120cf1a831.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}

Dry run a user deletion.

Authorizations:
bearerHttpAuthentication
path Parameters
userId
required
string <uuid>

ID for the user being manipulated. Can be set to me when viewing a user.

Responses

Request samples 

curl --request DELETE \
  --url {{API_BASE_URL}}/users/8c640fd5-268c-4ae0-9e35-2f120cf1a831/dry-run.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

Content type
application/json
{
  • "header": {
    },
  • "body": null
}