API v2: Collection Management 🆕¶

Overview¶

Collections are organizational containers for secrets in Fudo Enterprise’s vault system. They provide hierarchical structure, permission management, and access control for secret storage. Collections support both organizational vaults and personal vaults, with comprehensive permission inheritance and granular access policies.

Data Structures¶

`CollectionModel`¶
Attribute	Type	Required	Description
`id`	string		Read-only. Unique secret collection identifier.
`name`	string	yes	Collection name. Uniqueness is required in the combination with `parent_id` (case-insensitive).
`parent_id`	string		Parent collection identifier for hierarchical structure. Uniqueness is required in the combination with `name`.
`owner_id`	string		Read-only. Hidden. Protected. User ID of the personal vault owner.
`inherit_permissions`	boolean		Inherit permissions from parent collection.
`inheritance_target_collection_id`	string		Read-only. ID of the collection that permissions are inherited from.
`subcollections_count`	number		Read-only. Number of direct child collections.
`secrets_count`	number		Read-only. Number of descendant secrets.
`path_to_root_ids`	string-array		Read-only. Hidden. Ordered list of ancestor collection IDs.
`path_to_root_names`	string-array		Read-only. Hidden. Ordered list of ancestor collection names.
`accessible_parent_id`	string		Read-only. Hidden. Accessible parent collection ID.
`vault`	string		Read-only. Hidden. Vault type (organization, personal).
`contains_exposed_secrets`	boolean		Read-only. Indicates whether the collection contains secrets with exposure alerts.
`rights`	string-array		Read-only. List of rights the subject has to this object.
`created_at`	datetime		Read-only. Timestamp of creation.
`modified_at`	datetime		Read-only. Timestamp of modification.
`removed`	boolean		Read-only.

Retrieve Available Attributes of the CollectionModel¶

Request

Method	`GET`
Path	`/api/v2/objspec/collection`

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.

Note

Collections support hierarchical organization with parent-child relationships. Permission inheritance allows collections to automatically inherit access policies from parent collections.

List Collections¶

Request

Method	`GET`
Path	`/api/v2/collection`

GET /api/v2/collection

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.31.135.179/api/v2/collection'

Response

{
    "result": "success",
    "collection": [
        {
            "id": "8754997675608244225",
            "name": "Development Team",
            "inherit_permissions": false,
            "inheritance_target_collection_id": "8754997675608244225",
            "subcollections_count": 2,
            "secrets_count": 2,
            "contains_exposed_secrets": true,
            "rights": [
                "create",
                "delete",
                "modify",
                "move",
                "read"
            ],
            "created_at": "2026-03-25 01:46:50.823004-07",
            "modified_at": "2026-04-03 06:36:25.545952-07"
        }
    ]
}

Get Collection by ID¶

Request

Method	`GET`
Path	`/api/v2/collection/<id>`

GET /api/v2/collection/<id>

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.31.135.179/api/v2/collection/8754997675608244225'

Response

{
    "result": "success",
    "collection": {
        "id": "8754997675608244225",
        "name": "Development Team",
        "inherit_permissions": false,
        "inheritance_target_collection_id": "8754997675608244225",
        "subcollections_count": 2,
        "secrets_count": 2,
        "contains_exposed_secrets": true,
        "rights": [
            "create",
            "delete",
            "modify",
            "move",
            "read"
        ],
        "created_at": "2026-03-25 01:46:50.823004-07",
        "modified_at": "2026-04-03 06:36:25.545952-07"
    }
}

Create Collection¶

Request

Method	`POST`
Path	`/api/v2/collection`
Body	`CollectionModel`

POST /api/v2/collection

Example Request

curl -s -k -X POST \
  -H 'Authorization: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Database Credentials",
    "parent_id": "8754997675608244225",
    "inherit_permissions": true
  }' \
  'https://10.31.135.179/api/v2/collection'

Response

{
    "result": "success",
    "collection": [
        {
            "id": "8754997675608244228",
            "name": "Database Credentials",
            "parent_id": "8754997675608244225",
            "inherit_permissions": true,
            "inheritance_target_collection_id": "8754997675608244225",
            "subcollections_count": 0,
            "secrets_count": 0
        }
    ]
}

Update Collection¶

Request

Method	`PATCH`
Path	`/api/v2/collection/<id>`
Body	`CollectionModel`

PATCH /api/v2/collection/<id>

Example Request

curl -s -k -X PATCH \
  -H 'Authorization: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Database Credentials",
    "inherit_permissions": false
  }' \
  'https://10.31.135.179/api/v2/collection/8754997675608244228'

Response

{
    "result": "success",
    "collection": [
        {
            "id": "8754997675608244228",
            "name": "Database Credentials",
            "parent_id": "8754997675608244225",
            "inherit_permissions": false,
            "inheritance_target_collection_id": "8754997675608244228",
            "modified_at": "2026-04-17T14:45:00Z"
        }
    ]
}

Delete Collection¶

Request

Method	`DELETE`
Path	`/api/v2/collection/<id>`

DELETE /api/v2/collection/<id>

Example Request

curl -s -k -X DELETE \
  -H 'Authorization: <token>' \
  'https://10.31.135.179/api/v2/collection/8754997675608244228'

Response

{
    "result": "success"
}

Import Secrets to Collection¶

This endpoint imports secrets from a CSV file into a collection. The CSV file must be constructed according to the following rules:

The first row is a header row containing names corresponding to the API fields names (refer to API Documentation: API v2: Secrets).

The header row must include all fields that are required when manually creating a secret of specific type. Other fields are optional and can be left empty.

A comma (,) has to be used as a field separator.

Example CSV file:

name,type,login,domain,secret,uri
login,login,admin,portal.example.com,SuperSecure123!,https://portal.example.com/login
login2,login,db_admin,db.example.com,DbPassword2024,https://db.example.com/admin
note,note,,,Quarterly meeting notes: Q4 targets discussed.,
api_key,apikey,aws_service_account,api.aws.amazon.com,AKIAIOSFODNN7EXAMPLE,https://api.aws.amazon.com
cert,certificate,,,,
ssh_key,sshkey,,,,

Note

SSH private keys and certificates are typically stored in multi-line PEM format. When importing them from a CSV file, enclose the entire value in double quotes ("") so it is treated as a single CSV field.

Example CSV for a certificate secret:

name,type,login,domain,certificate,secret
"secret-1","certificate","","","-----BEGIN CERTIFICATE-----
MIID...EXAMPLE...DATA
-----END CERTIFICATE-----","-----BEGIN PRIVATE KEY-----
MIIE...EXAMPLE...DATA
-----END PRIVATE KEY-----"

Request

Method	`POST`
Path	`/api/v2/collection/<id>/secret_import`
Headers	`Content-Type: multipart/form-data`
Body	`CSV file upload`

POST /api/v2/collection/<id>/secret_import

Example Request

curl -s -k -X POST \
  -H 'Authorization: <token>' \
  -F 'file=@secrets.csv' \
  'https://10.31.135.179/api/v2/collection/8754997675608244225/secret_import'

Note

The CSV file should contain a header row with columns such as name, type, login, password, url, notes, etc.

Response

{
    "result": "success",
    "imported_count": 2,
    "failed_count": 0,
    "details": [
        {
            "name": "Database Admin",
            "status": "imported",
            "secret_id": "3260606130216239118"
        },
        {
            "name": "API Key",
            "status": "imported",
            "secret_id": "3260606130216239119"
        }
    ]
}