Skip to main content
API docs by Redocly

Passbolt API Documentation (4.9.0)

Download OpenAPI specification:Download

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

Public documentation for Passbolt's API

Welcome

This document is a raw low-level overview describing the API and its endpoints. For a higher-level overview of the API and some guides on interacting with the different endpoints, please follow the Developer guide.

Base URL

The API is served over HTTPS. All occurrences of {{API_BASE_URL}} referenced in the following documentation should be replaced by the base url of your passbolt installation domain, such as: https://<passbolt.your-organization.com>.

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": {
    }
}

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
foreignModel
required
string
Value: "resource"

Type for the foreign model being set as favorite.

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.

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

name
required
string
folder_parent_id
string or null <uuid>

Responses

Request samples

Content type
application/json
Example
{
  • "name": "folder name"
}

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/b2a72cb2-508c-43ad-b96f-697f7ad21635.json \
  --header 'Authorization: Bearer {{JWT_TOKEN}}'

Response samples

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

Update a folder.

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

name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "folder's new name"
}

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]
boolean

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"
}

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"

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"

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.

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

name
required
string
username
required
string
uri
required
string
description
string
resource_type_id
required
string <uuid>
folder_parent_id
string <uuid>
expired
string or null <date-time>
Array of objects

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "ae60d89c-f13b-4fb1-b2dc-c8dc806cac88",
  • "name": "NextCloud",
  • "username": "[email protected]",
  • "uri": "https://nextcloud.com/",
  • "description": null,
  • "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,
  • "personal": true,
  • "folder_parent_id": null,
  • "modifier": {
    },
  • "creator": {
    },
  • "secrets": [
    ],
  • "permission": {
    }
}

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 update

name
string
username
string
uri
string
description
string
resource_type_id
string <uuid>
expired
string or null <date-time>
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "NextCloud",
  • "username": "[email protected]",
  • "uri": "https://nextcloud.com/",
  • "resource_type_id": "a28a04cd-6f53-518a-967c-9963bf9cec51",
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ae60d89c-f13b-4fb1-b2dc-c8dc806cac88",
  • "name": "NextCloud",
  • "username": "[email protected]",
  • "uri": "https://nextcloud.com/",
  • "description": null,
  • "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,
  • "personal": true,
  • "folder_parent_id": null,
  • "modifier": {
    },
  • "creator": {
    },
  • "secrets": [
    ],
  • "permission": {
    }
}

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

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": {
    }
}

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": {
    }
}

Shares

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

Share a resource or folder.

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

Type for the foreign model being shared.

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 or folder.

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

Type for the foreign model being shared.

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": {
    }
}

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.

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.

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
}