POST method for creating collections with the API

Feature name

API call for creating collections
https://bitwarden.com/help/api/

Feature function

Use case : we have a git repo used to track and peer-review changes made on corporate collections (mainly add new ones and change access based on group policy). For now, we are locally leveraging the CLI app to create new collections (70+ users and soon nearly 150+, believe me, automation is much needed), with the help of a custom docker tool for parsing the repo. A properly automated process would instead trigger a Jenkins job in charge of syncing actual collections with the desired state described in the git repo. However it is currently not possible due to the need of a personal admin account to unlock the vault with the CLI.
The REST API currently have almost everything needed to properly automate such a use-case, but a single call is missing : the ability to create collections. There already are methods for editing existing collections (PUT, eg. allowing a new group to access the collection) and deleting (DELETE, eg. removing a collection after the corresponding project has ended). Having a POST method for creating collections without the need of a personal admin account would allow to create new collections as described in the reference (in our use-case, a git repo with YAML representation and a custom parsing tool).
From a security stand point, creating collection is not a sensitive operation, as newly created collections are empty and it’s up to users to share encrypted content in it. Moreover, there is already a collection editing method, which can be used maliciously if the automation system is compromised (eg. silently giving access to an unauthorized user/group). So adding a POST method will not lower the existing security level. It might actually even raise the overall safety by avoiding the need for admins to store there own credentials on automation components.

Related topics + references

  • The main feature request related to CRUD operations through API is here : Bitwarden REST API for automated secrets management on self-hosted server - #18 by Yonggan
    However it is not really relevant anymore, due to the present-days well documented API. This topic is also less specific than this new one, because I’m focusing on non-encrypted content while some of the comments in the original post were asking to manipulate encrypted secrets through the API
  • I also saw a few community comments saying that it’s possible to browse through the CLI code in order to learn how to create collections without the official API being leveraged. I had a quick glance to it, and I feel it might be possible, but I believe we shouldn’t have to fiddle around with unsupported practices in order to do such basic management operations. I think providing a complete CRUD model for unencrypted data easing large-team management is consistent with the rest of Bitwarden’s vision on overall password management and security : having a modern, reliable and integrated way of managing sensitive access control data.

Thanks for reading, feel free to correct me if I’m wrong or provide ressources that I might have missed while preparing this feature-request.

Thanks for the very detailed request @ImplicitDny!

There is a private API that is called from within an authenticated/decrypted vault. The Collection names are encrypted (and required), which means the use of the CLI or other client is needed. That’s why there isn’t a POST API for this one.

1 Like

Thanks for this quick answer. That’s… inconvenient, to the least. I can’t think of any “clean” way to automate collections management with this in mind. I understand why it’s technically not possible for now to interact with encrypted data through the API (and I don’t think it is otherwise very needed), but that obviously make managing large numbers of collections quite difficult.

Also, I never thought about collection names as sensitive data. Indeed, we are using the same value for collection name and external ID, precisely in order to make some automated checks easier. On the opposite, I’d rather consider group membership and stuff like that a more critical intel than collection names.

Is there any chance to see this change at some point ?

From our standpoint, we’d like to keep as much information private to you as possible. Users/groups are usually part of another system and are added/synchronized automatically, whereas collection names could potentially reveal customer names, projects, etc.

That being said - I don’t think it’s an invalid request to make automation more feasible :slight_smile:

1 Like

Yep, I think I get this, as much privacy as possible is a good standpoint. Maybe a “public name” system could allow automation without interfering with “private names” ? So that the end product would show the public name if no private name is available (not added or vault not unlocked), and the private name otherwise ? I’m not very convinced with this, to be honest…

Other idea might be to have a dedicated service account for organizations, which somehow wouldn’t be allowed to access encrypted secrets but still be able to manage private “meta” informations like collection names ? Service account only for collections would surely be totally overkill. But I’m not an expert (yet) on how all Bitwarden objects are stored. There might be other “name-like” stuff that would beneficiate from such a trick ? Not very convinced by this either…

For now the mandatory way is to store personal admin credentials somewhere, which is awful :no_mouth:

You can checkout this github Repository: Extended-Bitwarden-REST-API.
Maybe it helps you :slight_smile:

1 Like

I did when searching for a better way to automate. I even had a look on how you were managing collections, specifically. Sadly I think the problem will still be the same, personal admin credential management for “robotic” tasks is still on the way.

I’ll keep an eye on your work either way. If it can do what we do, but do it better, we might consider switching to it instead of cooking our own worryingly bubbling potion :slight_smile:

@ImplicitDny Shure it would be nice if the API could handle this. But my intention with the Extended API was to fix that missing hole as a workaround

1 Like

I’ll surely give it a try !

1 Like