Groups API¶

Access Grid¶

The following grid describes the valid combinations of Resources and Activities.

Specifying Ids¶

In places where you see an id placeholder like BLOBID or USERID, you may either specify a UUID like EB77EFD1-9E0C-4E4B-B2E1-C1AD7EA09CD2 or a special wildcard string .* that matches any id in that position (any user in the account, any document vault, etc). These compose, so specifying Vault::.*::Document::.* would match any document in any vault.

In the case of User and GroupMembership, you can also specify $[id=self.id] for the user id. This allows members of a Group with this policy to access only themselves. For instance, if Jane and John were both in a Group with policy U on User::$[id=self.id], both would be able to update themselves. However Jane would not be able to update John or vice versa. Similarly, a Group with policy Group::0000000-0000-0000-0000-000000000000::GroupMembership::$[id=self.id] would allow any group members to add themselves to the group with id 0000000-0000-0000-0000-000000000000.

Ownership¶

The vault structure and access control options listed above cover many use cases, but some more complex situations need additional flexibility. To address those, there is another layer that you may choose to use when modeling your data: ownership. Users and blobs can optionally have an owner. Group policies can limit users to only operate on documents owned by themselves or specific other owners. This allows you to easily express concepts like “Users can only see and operate on their own data” or “Customer service representatives can temporarily read a specific user’s documents” without needing to resort to complex server side logic or create a vault for each user.

[
    {
        "Resources":[
            "Vault::0000000-0000-0000-0000-000000000000::Search::",
            "Vault::0000000-0000-0000-0000-000000000000::Document::$[Owner=self]"
        ],
        "Activities":"R"
    }
]

[
    {
        "Resources":[
            "Vault::0000000-0000-0000-0000-000000000000::Search::",
            "Vault::0000000-0000-0000-0000-000000000000::Document::.*"
        ],
        "Activities":"R"
    }
]

Example Group Policies¶

Members of a Group assigned the following sample policy will have the ability to create and list all Vaults in the Account. In addition, they can create and list all Documents in the Vault with ID 0000000-0000-0000-0000-000000000000.

[
    {
        "Resources":[
            "Vault::",
            "Vault::0000000-0000-0000-0000-000000000000::Document::"
        ],
        "Activities":"CRUD"
    }
]

Members of a Group assigned the following sample policy will have only read and list access to Documents and BLOBs in all Vaults in the Account.

[
    {
        "Resources": ["Vault::.*", "Vault::.*::Document::.*", "Vault::.*::Blob::.*"],
        "Activities": "R"
    }
 ]

Members of a Group assigned the following sample policy will be able to search all users in the account.

[
    {
        "Resources": ["User::.*"],
        "Activities": "R"
    }
 ]

Members of a Group assigned the following sample policy will be able to search all documents in the vault.

[
   {
     "Resources":[
         "Vault::0000000-0000-0000-0000-000000000000::Document::.*",
         "Vault::0000000-0000-0000-0000-000000000000::Search::"
     ],
     "Activities":"R"
   }
]

Members of a Group assigned the following policy can freely create and access documents for themselves within a certain vault.

[
    {
        "Resources": [
            "Vault::0000000-0000-0000-0000-000000000000::Document::$[Owner=self]",
            "Vault::0000000-0000-0000-0000-000000000000::Blob::$[Owner=self]"
        ],
        "Activities":"CRUD"
    }
]

Members of a Group assigned the following policy can view any documents and blobs created by a particular user.

[
    {
        "Resources": [
            "Vault::.*::Document::$[Owner=0000000-0000-0000-0000-000000000000]",
            "Vault::.*::Blob::$[Owner=0000000-0000-0000-0000-000000000000]"
        ],
        "Activities":"R"
    }
]

Members of a Group assigned the following policy can add any user to the group with id 0000000-0000-0000-0000-000000000000.

[
    {
        "Resources": [
            "Group::0000000-0000-0000-0000-000000000000::GroupMembership::.*"
        ],
        "Activities":"C"
    }
]

Create a Group¶

POST /v1/groups¶

Create a Group with a name for the account with a policy.

Form Parameters:
	name – string(req’d) - name of group, must be unique policy – b64 string(optional, default: ‘’) - base64 encoded policy string user_ids – string(optional, default: ‘’) - comma separated list of user_id, non-existent users ignored
Request Headers:
	Authorization – API_KEY or ACCESS_TOKEN
Status Codes:	200 OK – success

Example Policy

[
    {
        "Activities": "C",
        "Resources": [
            "Vault::"
        ]
    }
]

Example Request

curl https://api.truevault.com/v1/groups \
    -X POST \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "name=test_group&policy=W3siUmVzb3VyY2VzIjpbIlZhdWx0OjoiXSwiQWN0aXZpdGllcyI6ICJDIn1d"

Example Response

{
    "group": {
        "policy": [
            {
                "Activities": "C",
                "Resources": [
                    "Vault::"
                ]
            }
        ],
        "user_ids": [],
        "group_id": "0000000-0000-0000-0000-000000000000",
        "name": "test_group"
    },
    "result": "success",
    "transaction_id": "0000000-0000-0000-0000-000000000000"
}

Read a Group¶

GET /v1/groups/(string: group_id)¶

Retrieves policy information about a Group.

Query Parameters:
	full – boolean(optional, default: ‘false’) - retrieve member IDs for the Group
Parameters:	group_id – string(req’d)
Request Headers:
	Authorization – API_KEY or ACCESS_TOKEN
Status Codes:	200 OK – success 404 Not Found – Group does not exist

Example Request

curl https://api.truevault.com/v1/groups/0000000-0000-0000-0000-000000000000 \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "group": {
        "group_id": "0000000-0000-0000-0000-000000000000",
        "name": "test_group",
        "policy": [
            {
                "Activities": "C",
                "Resources": [
                    "Vault::"
                ]
            }
        ]
    },
    "result": "success",
    "transaction_id": "0000000-0000-0000-0000-000000000000"
}

List all Groups¶

GET /v1/groups¶

Lists all groups for the Account.

Request Headers:
	Authorization – API_KEY or ACCESS_TOKEN
Status Codes:	200 OK – success

Example Request

curl https://api.truevault.com/v1/groups \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "groups": [
        {
            "group_id": "0000000-0000-0000-0000-000000000000",
            "name": "test_group",
            "policy": [
                {
                    "Activities": "C",
                    "Resources": [
                        "Vault::"
                    ]
                }
            ]
        }
    ],
    "result": "success",
    "transaction_id": "0000000-0000-0000-0000-000000000000"
}

Update a Group¶

PUT /v1/groups/(string: group_id)¶

Updates a Group’s policy, name, and attached users

Parameters:	group_id – string(req’d)

PUT a JSON object with the following fields:

• name string(optional) - new name for Group
• policy: array(optional) - new policy for Group
• user_ids: array(optional) - array of user id strings for this update request
• user_operation string(optional, default: ‘APPEND’) - ‘APPEND’ or ‘REMOVE’ the provided list of user ids to the group

Request Headers:

• Authorization: API_KEY or ACCESS_TOKEN
• Content-Type: application/json

Status Codes:

• 200: success
• 404: Group does not exist

Example Request

curl https://api.truevault.com/v1/groups/810b5375-a9b3-4911-bce5-c26cfdab774a \\
    -X PUT \\
    -H 'Content-Type: application/json' \\
    -u [API_KEY | ACCESS_TOKEN]: \\
    -d '{"name": "New group name"}'

Example Response

{
  "group": {
    "group_id": "810b5375-a9b3-4911-bce5-c26cfdab774a",
    "id": "810b5375-a9b3-4911-bce5-c26cfdab774a",
    "name": "New group name",
    "policy": [],
    "user_ids": []
  },
  "result": "success",
  "transaction_id": "f6a89eeb-e068-49ba-a1f0-c26102dd6a30"
}

curl https://api.truevault.com/v1/groups/0000000-0000-0000-0000-000000000000 \\
    -X PUT \\
    -u [API_KEY | ACCESS_TOKEN]: \\
    -d "name=customers&policy=W3siUmVzb3VyY2VzIjpbIlZhdWx0OjoiXSwiQWN0aXZpdGllcyI6ICJDIn1d"

{
    "group": {
        "group_id": "0000000-0000-0000-0000-000000000000",
        "name": "test_group_1",
        "policy": [
            {
                "Activities": "C",
                "Resources": [
                    "Vault::"
                ]
            }
        ],
        "user_ids": []
    },
    "result": "success",
    "transaction_id": "0000000-0000-0000-0000-000000000000"
}

Add users to a Group¶

POST /v1/groups/(string: group_id)/membership¶

Add users to a group.

Having Update access to the Group will allow you to add members via this endpoint, but since the only action taken is adding members, a less powerful policy that allows Create on GroupMembership for the relevant Group will also work.

Parameters:	group_id – string(req’d)
Request Headers:
	Authorization – API_KEY or ACCESS_TOKEN Content-Type – application/json
Status Codes:	200 OK – success 404 Not Found – Group does not exist

Example Request

curl https://api.truevault.com/v1/groups/00000000-0000-0000-0000-000000000000/membership \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
        "user_ids": [
            "00000000-0000-0000-0000-000000000000",
            "11111111-1111-1111-1111-111111111111"
        ]
    }'

Example Response

{
    "result": "success"
}

Remove users from a Group¶

DELETE /v1/groups/(string: group_id)/membership/(string: user_ids)¶

Remove users to a group. Users must be in the group at invocation time, or an error will result and no action will be taken

Having Update access to the Group will allow you to remove members via this endpoint, but since the only action taken is adding members, a less powerful policy that allows Delete on GroupMembership for the relevant Group will also work.

Parameters:	group_id – string(req’d) The UUID for the group user_ids – string(req’d) Comma-separated list of UUIDs for user to remove from this group. These users must be members of the group when invoked, otherwise an error will result and no action will be taken.
Request Headers:
	Authorization – API_KEY or ACCESS_TOKEN Content-Type – application/json
Status Codes:	200 OK – success 404 Not Found – Group does not exist or users do not exist or are not members of gorup

Example Request

curl https://api.truevault.com/v1/groups/00000000-0000-0000-0000-000000000000/membership/00000000-0000-0000-0000-000000000000,00000000-0000-0000-0000-000000000000 \
    -X DELETE \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "result": "success"
}

Delete a Group¶

DELETE /v1/groups/(string: group_id)¶

Deletes a group and detaches the Group from all users.

Parameters:	group_id – string(req’d)
Request Headers:
	Authorization – API_KEY or ACCESS_TOKEN
Status Codes:	200 OK – success 404 Not Found – Group does not exist

Example Request

curl https://api.truevault.com/v1/groups/0000000-0000-0000-0000-000000000000 \
    -X DELETE \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "group": {
        "group_id": "0000000-0000-0000-0000-000000000000",
        "name": "test_group_1",
        "policy": [
            {
                "Activities": "C",
                "Resources": [
                    "Vault::"
                ]
            }
        ],
        "user_ids": []
    },
    "result": "success",
    "transaction_id": "0000000-0000-0000-0000-000000000000"
}