Vaults and vault access

Vaults connect storage to handlers and can be managed by multiple principals. All routes on this page require a consumer token and use vault membership for authorization.

Routes

Route	Required fields	Optional fields and behavior
ANY /v1/vault/search	—	id limits results to one accessible vault.
ANY /v1/vault/view	handler	id updates; omit it to create. action: "refresh" returns a record without saving.
ANY /v1/vault/delete	id	action: "refresh" reports whether deletion is possible.
ANY /v1/vault/handler/search	—	vault restricts options to a vault; standard pagination fields.
ANY /v1/vault/manage/add	vault, principal, role	—
ANY /v1/vault/manage/remove	vault, principal	—
ANY /v1/vault/manage/search	vault	role and standard pagination fields.
ANY /v1/vault/manage/update	vault, principal, role	—
ANY /v1/vault/manage/view	vault, principal	—
ANY /v1/vault/bucket/add	vault, bucket, role	role must be member.
ANY /v1/vault/bucket/remove	vault, bucket	—
ANY /v1/vault/bucket/search	vault	Standard pagination fields.
ANY /v1/vault/bucket/update	vault, bucket, role	role must be member.
ANY /v1/vault/bucket/view	vault, bucket	—

Create or update a vault

/v1/vault/view creates a vault without id and updates one with id. New vaults create a membership group with the caller as owner. Updating requires owner or admin membership. A handler is always required; a new vault may use a private handler only when called by a root principal.

Field	Required	Type	Description
id	No	UUID	Existing vault ID for update or refresh.
handler	Save	UUID	Handler selected for the vault. It must be an allowed option for an existing vault.
host	Save value	String	Vault host value to store.
name	Save value	String	Vault name to store.
config	Save value	JSON object or JSON object string	Vault configuration. Native JSON objects are accepted.
meta	Save value	JSON object or JSON object string	Vault metadata. Native JSON objects are accepted.
priority	Save value	Number	Vault priority.
expires	No	String	Accepted by the request path but not persisted by the current save operation; do not rely on it changing the vault.
action	No	String	refresh returns a template or existing record and skips saving.

curl -sS https://api.bigfs.m7.org/v1/vault/view \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"primary-vault",
    "host":"vault.example.invalid",
    "handler":"HANDLER_UUID",
    "config":{},
    "meta":{},
    "priority":10
  }'

The response data contains record with the saved vault and log. Vault records contain id, name, host, config, meta, handler, priority, created, modified, and expires; config and meta are returned as JSON objects.

/v1/vault/search returns only vaults for which the caller has membership. When id is supplied, it is returned only if accessible.

Delete a vault

Only a vault owner or admin may delete a vault. Send action: "refresh" to check the number of associated remote assets. Deletion is rejected while remote assets remain; a successful delete removes the vault's access relationships.

Field	Required	Type	Description
id	Yes	UUID	Vault to inspect or delete.
action	No	String	refresh reports deletion status instead of deleting.

Find available handlers

/v1/vault/handler/search returns public handler options. Supplying vault requires owner or admin access and returns the options available to that vault, including its assignments. The paged items entries include source, handler_assignment when assigned, and a handler summary with id and name.

Field	Required	Type	Description
vault	No	UUID	Vault whose available handler options to list.
limit, cursor, offset, page_number	No	Pagination fields	See pagination.

Manage vault principals

Vault-management records use only the exact roles owner and admin.

Route	Caller requirement	Result
/v1/vault/manage/add	Vault owner	Adds an active principal.
/v1/vault/manage/remove	Vault owner	Removes a management entry.
/v1/vault/manage/search	Vault owner or admin	Returns management entries.
/v1/vault/manage/update	Vault owner	Changes the role.
/v1/vault/manage/view	Named principal, vault owner, or vault admin	Returns one entry.

The final owner cannot be removed or demoted.

Field	Required	Type	Description
vault	Yes	UUID	Vault ID.
principal	Add, remove, update, view	UUID	Principal ID.
role	Add and update	Enum	owner or admin; filters search when supplied.
limit, cursor, offset, page_number	No	Pagination fields	Accepted only by search.

add, update, and view return data.management (id, principal, role, timestamps) and a data.principal summary.

Link buckets to a vault

Vault bucket routes manage the buckets linked to a vault. Vault owner or admin access is required. The only accepted role is member; it must be supplied for add and update.

Field	Required	Type	Description
vault	Yes	UUID	Vault ID.
bucket	Add, remove, update, view	UUID	Bucket to link.
role	Add and update	Literal	Must be member.
limit, cursor, offset, page_number	No	Pagination fields	Accepted only by search.

The data for add, update, and view contains bucket_access (id, bucket, role, timestamps) and a bucket summary with id and name.