Vault Management API – /object/org-collection fails with "Unprocessable Entity" when including groups

[MnkyArts (Liam Robinson)]

Hi everyone,

I’m currently working on automating collection creation for our Bitwarden organization using the Vault Management API (self-hosted instance).
The endpoint I’m using is:

POST /object/org-collection

According to the documentation, the payload should look like this:

{
  "organizationId": "3c89a31d-f1cc-4673-8d5a-ae2700f9860d",
  "name": "Shared Logins",
  "externalid": null,
  "groups": [
    {
      "id": "c4e31257-f3e1-4b13-895a-ae2700f9884e",
      "readOnly": false,
      "hidePasswords": false
    }
  ]
}

However, when I include the "groups" array, the request fails with a 422 Unprocessable Entity error:

{"response":{"error":{"code":422,"reason":"Unprocessable Entity","description":"The request was well-formed but was unable to be followed due to semantic errors."}},"statusCode":422}

If I remove the "groups" property entirely, the request works perfectly and the collection is created.

Here’s an example of what my logs look like in debug mode:

DEBUG - Request URL: http://localhost:8082/object/org-collection
DEBUG - Payload: {
  "organizationId": "2947ea9e-1d56-47e9-a683-b9e3c0842bb0",
  "name": "Testing API",
  "externalid": null,
  "groups": [
    {
      "id": "ca9aecbb-e058-441f-8697-986136be43d1",
      "readOnly": false,
      "hidePasswords": false
    }
  ]
}
DEBUG - Response status: 400
DEBUG - Response body: {"success":false,"message":"{\"response\":{\"error\":{\"code\":422,\"reason\":\"Unprocessable Entity\",\"description\":\"The request was well-formed but was unable to be followed due to semantic errors.\"}},\"statusCode\":422}"}

Without "groups", the collection is created successfully.
With "groups", every call fails with 422.

The Swagger API documentation explicitly shows groups as a valid field for POST /object/org-collection, but the server rejects any payload containing it with a 422 Unprocessable Entity error.

Is this a bug in the current Vault Management API implementation, or is there a specific payload format or precondition required when associating groups with new collections that isn’t reflected in the documentation?

Thanks in advance!
Liam

[MnkyArts (Liam Robinson)]

Update / Solution

I was able to resolve the issue.

It turns out that the groups array in the payload requires an additional property called "manage", which isn’t shown in the Swagger documentation. (thanks for making the clients open source)

Without it, the API returns a 422 Unprocessable Entity error.

Here’s a working example payload:

{
  "organizationId": "2947ea9e-1d56-47e9-a683-b9e3c0842bb0",
  "name": "Testing API",
  "externalId": null,
  "groups": [
    {
      "id": "ca9aecbb-e058-441f-8697-986136be43d1",
      "readOnly": false,
      "hidePasswords": false,
      "manage": false
    }
  ]
}

Once I added the "manage" field (set to either true or false), the request worked as expected and the collection was created successfully with the group associations.

Hopefully this helps anyone else running into the same issue!