Help Search


A Resource can be shared with another User or Group. Which essentially means adding permissions to the Resource for the User/Group.

Permissions in passbolt use some Access Control List (ACL) lingo. Mostly two concepts:

  • Access Control Object (ACO) that represents something that is wanted, like a resource and its secrets.
  • Access Request Object (ARO) represents something that wants an ACO, so a user or a group.

Get all AROs

In order to know the list of AROs with whom a Resource can be shared, you can use the search-aros endpoint.

To get the ARO list make a GET request to /share/search-aros.json

GET /share/search-aros.json

The response returned will have an array of json objects, each representing either a Group or a User.

    "header": {
        "id": "1e0b7ca1-8427-4ec4-a46e-b3dc4f11f878",
        "status": "success",
        "servertime": 1554968444,
        "action": "10807e9e-d525-5acc-b05d-cccbbd252a93",
        "message": "The operation was successful.",
        "url": "\/share\/search-aros.json",
        "code": 200
    "body": [
            "user_count": "18",
            "id": "bda0a05c-b1fa-58be-b5b9-446e65ace052",
            "name": "Group Name",
            "deleted": false,
            "created": "2018-01-08T13:39:25+00:00",
            "modified": "2018-01-08T13:39:25+00:00",
            "created_by": "d57c10f5-639d-5160-9c81-8a0c6c4ec856",
            "modified_by": "d57c10f5-639d-5160-9c81-8a0c6c4ec856"
            "id": "f848277c-5398-58f8-a82a-72397af2d450",
            "role_id": "a58de6d3-f52c-5080-b79b-a601a647ac85",
            "username": "[email protected]",
            "active": true,
            "deleted": false,
            "created": "2019-02-04T12:05:44+00:00",
            "modified": "2019-03-04T12:05:44+00:00",
            "profile": {}, // User profile object
            "groups_users": [
                    "id": "4f2a3f6e-1a3f-4f4a-a523-46c6b6d0f763",
                    "group_id": "05b68bd2-e4e8-4838-ac21-4661b27fb23b",
                    "user_id": "f848277c-5398-58f8-a82a-72397af2d450",
                    "is_admin": true,
                    "created": "2019-04-08T12:44:44+00:00"
                    "id": "6809e727-1219-4cfa-a201-1d3e997ca351",
                    "group_id": "73479f22-b387-4d4e-b625-b1cc0b7ed116",
                    "user_id": "f848277c-5398-58f8-a82a-72397af2d450",
                    "is_admin": true,
                    "created": "2019-04-08T12:10:03+00:00"
            "role": {
                "id": "a58de6d3-f52c-5080-b79b-a601a647ac85",
                "name": "user",
                "description": "Logged in user",
                "created": "2012-07-04T13:39:25+00:00",
                "modified": "2012-07-04T13:39:25+00:00"
            "gpgkey": {
                "id": "04481719-5d9d-5e22-880a-a6b9270601d2",
                "user_id": "f848277c-5398-58f8-a82a-72397af2d450",
                "armored_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----",
                "bits": 4096,
                "uid": "Ada Lovelace \u[email protected]\u003E",
                "key_id": "5D9B054F",
                "fingerprint": "03F60E958F4CB29723ACDF761353B5B15D9B054F",
                "type": "RSA",
                "expires": "2019-08-09T12:48:31+00:00",
                "key_created": "2015-08-09T12:48:31+00:00",
                "deleted": false,
                "created": "2019-04-04T12:05:49+00:00",
                "modified": "2019-04-04T12:05:49+00:00"
            "last_logged_in": ""

Take a note of the user_count key under group type AROs as that’s the exact number of secrets you’ll need to send in order to share a resource with that group.

Sharing a Resource

Sharing a Resource involves the following steps.

  1. Get the id of the Resource you want to share.
  2. Get the id of the ARO you want to share it with.
  3. Encrypt the plaintext secret for all users using their public keys.
  4. Send the ASCII armored encrypted message for each of the affected users to the API.

The payload takes a json object with keys for “permissions” and “secrets”. The “permission” key contains a json array where each object represents a Permission object for a user. While the “secrets” key contains a json array where each object represents a Secret object. At the very least, it contains the user_id and OpenPGP encrypted armored message.

To generate the encrypted message, you can use

$ echo <plaintext_password> | gpg -r <gpg_uid> -e -a

The search-aros endpoint described above outputs the gpg details for individual users like their armored_key, uid, key_id and fingerprint. For Groups, you can make a GET request to /groups/<group_id>.json endpoint. For more info, check the View a group page.

Based on the trust level of the public key gpg might complain about There is no assurance this key belongs to the named user If you trust the key, you can proceed by responding ‘y’

Upon confirmation, gpg outputs the ascii armored message

$ echo <plaintext_password> | gpg -r <gpg_uid> -e -a



This needs to be done for each user gaining access to the secret So the request body will look like

  "permissions": [
      "is_new": true,
      "aro": "Group",
      "aro_foreign_key": "36563004-3f25-50c0-b22e-6554c3ccc4e7",
      "aco": "Resource",
      "aco_foreign_key": "8e3874ae-4b40-590b-968a-418f704b9d9a",
      "type": 7
  "secrets": [
      "user_id": "8d04cf98-716b-5f6d-9fe8-c130f8992646",
      "data":"-----BEGIN PGP MESSAGE-----"

Simulate Sharing

Passbolt API allows you to simulate a share before actually going through with this. This way you can see if the params pass the validation checks. To simulate sharing a resource you can make a POST request to /share/simulate/resource/<resourceId>.json where resourceId is the id of the Resource you wish to share.

POST /share/simulate/resource/<resourceId>.json

If the resource can be shared safely, this returns an associative array that contains a list of new users who will have access to the resource and a list of users who will lose their access. These lists can be used to encrypt the secrets for the users who get access and to remove the secrets of the users who lost their access.

    "header": {
        "id": "499657b1-463c-49e3-99d0-7d4bca7392c2",
        "status": "success",
        "servertime": 1554972001,
        "action": "7df37cb5-cfb9-57c2-a7a5-b65c9f573de0",
        "message": "The operation was successful.",
        "url": "\/share\/simulate\/resource\/8e3874ae-4b40-590b-968a-418f704b9d9a.json",
        "code": 200
    "body": {
        "changes": {
            "added": ["<uuid1>", "<uuid2>"],
            "removed": ["<uuid3>", "<uuid4>"]

Final sharing

If the simulation returns a success response, you can go ahead with sharing your resource. To share a resource you can make a PUT request to /share/simulate/resource/<resourceId>.json where resourceId is the id of the Resource you wish to share.

PUT /share/resource/<resourceId>.json

The request schema is same as above while the response can be either of the following.

Code Description
200 OK
The resource is shared successfully.
400 Bad Request
The resourceId supplied is not a valid UUID
403 Authentication Failure
The user making the request is not authenticated
404 Not Found
The resource either does not exist or
The user does not have access permission or
Invalid number of secrets sent.

Last updated

This article was last updated on April 23rd, 2019.

For another perspective on the API you browse the OpenAPI 2.0 specifications using the dedicated API reference site (Swagger UI).

API Reference

You can also find the latest OpenAPI 2.0 specifications directly on the dedicated repository.

OpenAPI Specs repository
🍪   Do you accept cookies for statistical purposes? (Read more) Accept No thanks!