Groups

Organize vaults into groups and scope API key access

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

cURL

curl -X POST https://api.case.dev/vault/groups \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "description": "All Acme Corp matters"
  }'

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

Field	Type	Description
name	string	Required. Display name for the group
description	string	Optional 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

cURL

curl https://api.case.dev/vault/groups \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

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

cURL

curl -X PATCH "https://api.case.dev/vault/groups/$GROUP_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}'

Field	Type	Description
name	string	New display name (slug is regenerated)
description	string | null	New description, or null to clear

---

Delete a group

Soft-deletes a group. The group must have no vaults assigned.

Endpoint

DELETE /vault/groups/:groupId

cURL

curl -X DELETE "https://api.case.dev/vault/groups/$GROUP_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

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

cURL

curl -X POST https://api.case.dev/vault \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme - Contract Review", "groupId": "grp_abc123"}'

Move an existing vault

Use PATCH /vault/:id to move a vault into (or between) groups:

cURL

curl -X PATCH "https://api.case.dev/vault/$VAULT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"groupId": "grp_abc123"}'

---

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.

Operation	Scoped key	Unscoped key
List groups	Only allowed groups	All groups
List vaults	Only vaults in allowed groups	All vaults
Get vault by ID	Allowed groups only (404 otherwise)	All vaults
Create vault without groupId	Denied (403)	Allowed
Create vault in allowed group	Allowed	Allowed
Create vault in other group	Denied (403)	Allowed
Remove vault from group	Denied (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:

Event	When
vault.group.created	Group created
vault.group.updated	Group renamed or description changed
vault.group.deleted	Group soft-deleted