Variables - Bentra

Variables reach a workflow’s steps as environment variables. They come from variable collections (reusable sets owned by a workspace, shareable with others and attachable to any number of workflows) and from the workflow’s own variables, which override collection values. Among attached collections, a later one overrides an earlier one. Secret values are encrypted with a key unique to your organization and are never returned: responses show a masked display_value.

Method	Path	Scope	MCP tool
`GET`	`variable-collections/?workspace=`	`read:variables`	`list_variable_collections`
`GET`	`variable-collections/{id}/`	`read:variables`	`get_variable_collection`
`POST`	`variable-collections/`	`edit:variables`	`create_variable_collection`
`PATCH`	`variable-collections/{id}/`	`edit:variables`	`update_variable_collection`
`DELETE`	`variable-collections/{id}/`	`edit:variables`	`delete_variable_collection`
`PATCH`	`variable-collections/{id}/sharing/`	`edit:variables`	`set_collection_sharing`
`POST`	`variable-collections/{id}/variables/`	`edit:variables`	`add_collection_variable`
`PATCH`	`variable-collections/{id}/variables/{variable_id}/`	`edit:variables`	`update_collection_variable`
`DELETE`	`variable-collections/{id}/variables/{variable_id}/`	`edit:variables`	`delete_collection_variable`
`GET`	`workflows/{id}/variables/`	`read:variables`	`list_workflow_variables`
`POST`	`workflows/{id}/variables/`	`edit:variables`	`add_workflow_variable`
`PATCH`	`workflows/{id}/variables/{variable_id}/`	`edit:variables`	`update_workflow_variable`
`DELETE`	`workflows/{id}/variables/{variable_id}/`	`edit:variables`	`delete_workflow_variable`
`POST`	`workflows/{id}/variable-collections/`	`edit:variables`	`attach_collection`
`DELETE`	`workflows/{id}/variable-collections/{collection_id}/`	`edit:variables`	`detach_collection`

Permissions: reading collections needs org.view_variable_collections. Owners and admins (org.manage_variable_collections) can create and change any collection. Members (org.create_variable_collections) can create collections owned by a workspace they belong to, except the default workspace, and change any collection their workspaces own, whoever created it. A workflow’s variables and attached collections need workflow.manage_variables.

A variable

{"id": "…", "key": "AWS_REGION", "display_value": "eu-west-1", "is_secret": false, "treat_as_json": false}

Body for creating or changing one:

Field	Notes
`key`	Letters, digits and underscores, not starting with a digit. Unique within the collection or workflow. Required on create.
`value`	The value. For a secret, write-only.
`is_secret`	Store the value encrypted; it’s never returned.
`treat_as_json`	Validate the value as JSON.

PATCH changes only what you send. Changing a key or value of a secret never reveals the old value.

Secrets and agentsAn agent can set a secret if you give it the value, but the value then passes through the conversation. Prefer entering secret values in Bentra.

Collections

`GET variable-collections/`

Owners and admins see every collection. Everyone else sees the ones usable in a workspace they belong to: owned by it, shared with it, or shared with every workspace. ?workspace=<slug> narrows the list to the collections that workspace’s workflows can attach. Paginated.

{"count": 1, "next": null, "previous": null,
 "results": [{"id": "…", "name": "AWS prod", "description": "", "workspace": "platform",
              "visibility": "selected_workspaces", "shared_with": ["data"],
              "created_by": "dana@acme.com", "created_at": "…", "updated_at": "…"}]}

workspace owns the collection; its members manage it. visibility is this_workspace, selected_workspaces (the ones in shared_with) or all_workspaces. Shared workspaces can attach it but not change it.

`GET variable-collections/{id}/`

The collection plus variables.

`POST variable-collections/`

{"workspace": "platform", "name": "AWS prod", "description": "…", "visibility": "selected_workspaces", "workspaces": ["data"]}

→ 201. workspace is the owning workspace; visibility (default this_workspace) and workspaces are optional. 403 if you can’t create collections there. 502 if secret storage is unavailable.

`PATCH variable-collections/{id}/`

{"name": "…", "description": "…"}.

`DELETE variable-collections/{id}/`

Deletes the collection, its variables and their secrets, and detaches it from workflows. Returns 204. {"workspace": "platform", "visibility": "selected_workspaces", "workspaces": ["data", "ml"]}, every field optional.

workspace moves the collection. A member must belong to both workspaces, and neither can be the default workspace. The old workspace stays shared while its workflows have the collection attached.
workspaces replaces the shared list; [] stops sharing. Only owners and admins can use all_workspaces or share with the default workspace. When a member saves, workspaces they can’t manage stay on the list.
Returns 409 with blocking_workflows (slug, name, workspace) when a workflow in a workspace that would lose access still has the collection attached. Nothing changes.

A workflow’s variables

`GET workflows/{id}/variables/`

{"success": true,
 "variables": [{"id": "…", "key": "BUCKET_PREFIX", "display_value": "acme-", "is_secret": false, "treat_as_json": false}],
 "collections": [{"id": "…", "name": "AWS dev", "order": 1}, {"id": "…", "name": "AWS prod", "order": 2}],
 "overrides": [{"key": "AWS_SECRET_ACCESS_KEY",
                "used": {"type": "collection", "id": "…", "name": "AWS prod"},
                "overridden": [{"type": "collection", "id": "…", "name": "AWS dev"}]}]}

collections is in precedence order: later ones override earlier ones, and the workflow’s own variables override them all. overrides lists every key defined in more than one place, sorted by key: used is the definition a run gets, overridden the ones it ignores (nearest first). type is collection or workflow. Only keys are compared; no values are read. A run decrypts only the used definitions, so a broken overridden secret never fails it.

`POST workflows/{id}/variable-collections/`

{"collection_id": "…"} attaches a collection usable in the workflow’s workspace (its own, one shared with it, or one shared with every workspace), after the existing ones. 404 if it isn’t usable there; 409 if already attached.

`DELETE workflows/{id}/variable-collections/{collection_id}/`

Detaches it.

​A variable

​Collections

​GET variable-collections/

​GET variable-collections/{id}/

​POST variable-collections/

​PATCH variable-collections/{id}/

​DELETE variable-collections/{id}/

​PATCH variable-collections/{id}/sharing/

​A workflow’s variables

​GET workflows/{id}/variables/

​POST workflows/{id}/variable-collections/

​DELETE workflows/{id}/variable-collections/{collection_id}/

A variable

Collections

`GET variable-collections/`

`GET variable-collections/{id}/`

`POST variable-collections/`

`PATCH variable-collections/{id}/`

`DELETE variable-collections/{id}/`

`PATCH variable-collections/{id}/sharing/`

A workflow’s variables

`GET workflows/{id}/variables/`

`POST workflows/{id}/variable-collections/`

`DELETE workflows/{id}/variable-collections/{collection_id}/`