Skip to main content

​
The problem

Every API key with vault access can read and write all vaults in your organization. When different teams, clients, or integrations share an account, that’s too broad.

​
The solution

Vault groups let you:
  1. Organize — group vaults by client, matter type, or team
  2. Restrict — scope API keys so they only see vaults in specific groups
  3. Audit — every group create, update, and delete is logged

​
Create a group

Endpoint
POST /vault/groups

const group = await client.vault.groups.create({
  name: 'Acme Corp',
  description: 'All Acme Corp matters'
});

console.log(group.id);    // Use this to assign vaults
console.log(group.slug);  // Auto-generated: "acme-corp"
Response
{
  "id": "grp_abc123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "description": "All Acme Corp matters",
  "createdAt": "2025-02-17T10:30:00Z",
  "updatedAt": "2025-02-17T10:30:00Z"
}
FieldTypeDescription
namestringRequired. Display name for the group
descriptionstringOptional description
The slug is auto-generated from the name and must be unique across your organization—including soft-deleted groups.

​
List groups

Endpoint
GET /vault/groups

const { groups } = await client.vault.groups.list();

for (const group of groups) {
  console.log(`${group.name} (${group.slug})`);
}
Response
{
  "groups": [
    {
      "id": "grp_abc123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "description": "All Acme Corp matters",
      "createdAt": "2025-02-17T10:30:00Z",
      "updatedAt": "2025-02-17T10:30:00Z"
    }
  ],
  "total": 1
}
If your API key is scoped to specific groups, this endpoint returns only those groups.

​
Update a group

Rename a group or change its description.
Endpoint
PATCH /vault/groups/:groupId

const updated = await client.vault.groups.update(groupId, {
  name: 'Acme Corporation',
  description: 'Updated description'
});
FieldTypeDescription
namestringNew display name (slug is regenerated)
descriptionstring | nullNew description, or null to clear

​
Delete a group

Soft-deletes a group. The group must have no vaults assigned.
Endpoint
DELETE /vault/groups/:groupId

await client.vault.groups.delete(groupId);
You must move or delete all vaults in a group before deleting it. Attempting to delete a group with assigned vaults returns 409 Conflict.

​
Assign vaults to groups

​
When creating a vault

Pass groupId to place a new vault into a group:
Endpoint
POST /vault

const vault = await client.vault.create({
  name: 'Acme - Contract Review',
  groupId: 'grp_abc123'
});

​
Move an existing vault

Use PATCH /vault/:id to move a vault into (or between) groups: 
// Move vault into a group
await client.vault.update(vaultId, { groupId: 'grp_abc123' });

// Remove vault from its group (unscoped keys only)
await client.vault.update(vaultId, { groupId: null });

​
Scoped API keys

API keys can be restricted to specific vault groups. A scoped key can only:
  • List and access vaults within its allowed groups
  • Create new vaults in those groups (must provide groupId)
  • See only the groups it has access to
Scoped keys cannot create, update, or delete groups themselves.
OperationScoped keyUnscoped key
List groupsOnly allowed groupsAll groups
List vaultsOnly vaults in allowed groupsAll vaults
Get vault by IDAllowed groups only (404 otherwise)All vaults
Create vault without groupIdDenied (403)Allowed
Create vault in allowed groupAllowedAllowed
Create vault in other groupDenied (403)Allowed
Remove vault from groupDenied (403)Allowed
Manage groups (create/update/delete)Denied (403)Allowed
Create scoped API keys in the Console under API Keys. Select the Vault service, then check the groups you want the key to access. Leaving all groups unchecked gives full vault access.

​
Audit events

Every group lifecycle action emits an audit event:
EventWhen
vault.group.createdGroup created
vault.group.updatedGroup renamed or description changed
vault.group.deletedGroup soft-deleted