Groups API

TrueVault Groups provides a way to administer user access to resources. A Group is comprised of a UUID, a name, and a policy. A Group Policy describes both the Resources and Activities available to Group members.

A Group Policy is a list of policy objects. Each policy object contains two key/value pairs:

  • Resources: list of resource matchers. These are strings of ::-delimited tokens that refer to specific objects or sets of objects in TrueVault. See below for more on the syntax of matchers.
  • Activities: available operations on associated Resources, namely Create, Read, Update, and Delete. These are specified as a string containing the representative letters, as in "CRU" to mean create, read, and update (but not delete).

Access Grid

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

Resource Create Read Update Delete
Vault:: Create List
Vault::VAULTID Read Update Delete
Vault::VAULTID::Document:: Create List
Vault::VAULTID::Document::DOCUMENTID Read Update Delete
Vault::VAULTID::Blob:: Create List
Vault::VAULTID::Blob::BLOBID Read Update Delete
Vault::VAULTID::Schema:: Create List
Vault::VAULTID::Schema::SCHEMAID Read Update Delete
Vault::VAULTID::Search:: Read
User:: Create List
User::USERID Read Update Delete
User::USERID::Password Update
User::USERID::Message Create
User::$[id=self.id] Read Update Delete
UserSchema:: Create Read Update Delete
Group:: Create List
Group::GROUPID Read Update Delete
Group::GROUPID::GroupMembership::USERID Create Delete
PasswordResetFlow:: Create Read
PasswordResetFlow::FLOWID Read Delete
PasswordResetFlow::FLOWID::Email::USERID Create Delete

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.

Ownership Resource Specifiers

For restricting access to resources with specific owners, use the following resource specifiers in a group. An owner of self refers to the currently-authenticated TrueVault user.

Resource Create Read Update Delete
Vault::VAULTID::Document::$[Owner=self] Create Read Update Delete
Vault::VAULTID::Document::$[Owner=USERID] Create Read Update Delete
Vault::VAULTID::Document::$[Owner=.*] Create Read Update Delete
Vault::VAULTID::Blob::$[Owner=self] Create Read Update Delete
Vault::VAULTID::Blob::$[Owner=USERID] Create Read Update Delete
Vault::VAULTID::Blob::$[Owner=.*] Create Read Update Delete

A resource specifier of Vault::VAULTID::Document::.* or Vault::VAULTID::Blob::.* applies to all Documents/Blobs, including those that have an owner set. However, a resource specifier that has an owner doesn’t apply to Documents/Blobs without an owner set.

Changing Ownership

After a document is created, its owner can be changed or removed. The following table explains the group permissions required for any group member to change a document or blob’s owner:

Old Owner New Owner Required Permissions
Unowned USERB

Delete Vault::VAULTID::Document|Blob::BLOBID

Create Vault::VAULTID::Document|Blob::$[Owner=USERB]

USERA Unowned

Delete Vault::VAULTID::Document|Blob::$[Owner=USERA]

Create Vault::VAULTID::Document|Blob::

USERA USERB

Delete Vault::VAULTID::Document|Blob::$[Owner=USERA]

Create Vault::VAULTID::Document|Blob::$[Owner=USERB]

When determining the required permissions for ownership modification, it helps to think about it from the owners’ perspective. Removing the owner from a document will look like deleting the document to the old owner, so permission to delete that document is required.

Note that one still requires the Update permission in order to change the contents of the Document or Blob. The Update permission has no effect on modification of Ownership.

If you plan to update the Document or BLOB content while changing the owner, use the normal Update endpoint. If you only want to change the owner, consider the Update Document/BLOB Owner endpoints which only modify the owner attribute.

Searching with Ownership

In order to allow a User to search only the Documents they are owners of, they must have R permissions on these resources:

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

Note, in this example self can be substituted with a specific User ID or .*.

To allow a User to search any documents regardless of owner, grant a wildcard R permission on document and search:

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

If a user doesn’t have the Vault::VAULTID::Search:: permission, attempting to search will yield an HTTP 401.

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

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
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:
 
Status Codes:

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

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
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:
 
Status Codes:

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

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
GET /v1/groups

Lists all groups for the Account.

Request Headers:
 
Status Codes:

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

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
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/0000000-0000-0000-0000-000000000000 \\
    -X PUT \\
    -H 'Content-Type: application/json' \\
    -u [API_KEY | ACCESS_TOKEN]: \\
    -d '{"name": "New vault name"}'

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

A previous version of this API used an HTML form post instead of a JSON object. It is still supported for now, but new development should use the version described above.

  • name string(optional) - new name for Group
  • policy b64 string(optional) - new policy for Group, base64 encoded
  • user_ids string(optional) - comma separated list of user_id
    for this update request
  • operation string(optional, default: ‘APPEND’) - ‘APPEND’ or
    ‘REMOVE’ this group for the provided list of user_id

Request Headers:

  • Authorization: API_KEY or ACCESS_TOKEN
  • Content-Type: application/x-www-form-urlencoded

Status Codes:

  • 200: success
  • 404: Group does not exist

Example Request

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

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

Add users to a Group

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
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:
 
Status Codes:

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

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
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:
 
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

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
DELETE /v1/groups/(string: group_id)

Deletes a group and detaches the Group from all users.

Parameters:
  • group_id – string(req’d)
Request Headers:
 
Status Codes:

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