# Containers API - Reference

## GET /v1/containers

Lists a project’s containers.

Returned containers will be ordered by creation date; oldest to newest.

### Parameters

Name | Type | Description
--- | --- | ---
offset | integer | The starting index within the total list of the containers that you would like to retrieve.
limit | integer | The maximum number of containers to return (up to 100). The default limit is 10.

### Response Attributes

Name | Type | Description
--- | --- | ---
containers | list | Contains a list of dictionaries filled with container data
total | integer | The total number of containers available to the user
next | string | A HATEOAS URL to retrieve the next set of containers based on the offset and limit parameters. This attribute is only available when the total number of containers is greater than offset and limit parameter combined.
previous | string | A HATEOAS URL to retrieve the previous set of containers based on the offset and limit parameters. This attribute is only available when the request offset is greater than 0.

### Request:

    GET /v1/containers
    Headers:
        X-Auth-Token: <token>

### Response:

    {
        "containers": [
            {
                "consumers": [],
                "container_ref": "https://{barbican_host}/v1/containers/{uuid}",
                "created": "2015-03-26T21:10:45.417835",
                "name": "container name",
                "secret_refs": [
                    {
                        "name": "private_key",
                        "secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
                    }
                ],
                "status": "ACTIVE",
                "type": "generic",
                "updated": "2015-03-26T21:10:45.417835"
            }
        ],
        "total": 1
    }

### HTTP Status Codes

Code | Description
--- | ---
200 | Successful Request
401 | Invalid X-Auth-Token or the token doesn’t have permissions to this resource

## GET /v1/containers/{uuid}

Retrieves a single container.

### Response Attributes

Name | Type | Description
--- | --- | ---
name | string | (optional) Human readable name for the container
type | string | Type of container. Options: generic, rsa, certificate
secret_refs | list | A list of dictionaries containing references to secrets

### Request:

    GET /v1/containers/{uuid}
    Headers:
        X-Auth-Token: <token>

### Response:

    {
        "type": "generic",
        "status": "ACTIVE",
        "name": "container name",
        "consumers": [],
        "container_ref": "https://{barbican_host}/v1/containers/{uuid}",
        "secret_refs": [
            {
                "name": "private_key",
                "secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
            }
        ],
        "created": "2015-03-26T21:10:45.417835",
        "updated": "2015-03-26T21:10:45.417835"
    }

### HTTP Status Codes

Code | Description
--- | ---
200 | Successful Request
401 | Invalid X-Auth-Token or the token doesn’t have permissions to this resource
404 | Container not found or unavailable

## POST /v1/containers

Create a container

There are three different types of containers that can be created: generic, rsa, and certificate.

Generic

This type of container holds any number of references to secrets. Each secret reference is accompanied by a name. Unlike other container types, no specific restrictions are enforced on the contents name attribute.

RSA

This type of container is designed to hold references to only three different secrets. These secrets are enforced by their accompanied names: public_key, private_key, and private_key_passphrase.

Certificate

This type of container is designed to hold a reference to a certificate and optionally private_key, private_key_passphrase, and intermediates.

### Request Attributes

Name | Type | Description
--- | --- | ---
name | string | (optional) Human readable name for identifying your container
type | string | Type of container. Options: generic, rsa, certificate
secret_refs | list | A list of dictionaries containing references to secrets

### Request:

    POST /v1/containers
    Headers:
        X-Auth-Token: <token>

    Content:
    {
        "type": "generic",
        "name": "container name",
        "secret_refs": [
            {
                "name": "private_key",
                "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
            }
        ]
    }

### Response:

    {
        "container_ref": "https://{barbican_host}/v1/containers/{container_uuid}"
    }

### HTTP Status Codes

Code | Description
--- | ---
201 | Successful creation of the container
401 | Invalid X-Auth-Token or the token doesn’t have permissions to this resource
403 | Forbidden. The user has been authenticated, but is not authorized to create a container. This can be based on the user’s role or the project’s quota.

## DELETE /v1/containers/{uuid}

Deletes a container

### Request:

    DELETE /v1/containers/{container_uuid}
    Headers:
        X-Auth-Token: <token>

### Response:

    204 No Content

### HTTP Status Codes

Code | Description
--- | ---
204 | Successful deletion of a container
401 | Invalid X-Auth-Token or the token doesn’t have permissions to this resource
404 | Container not found or unavailable

## POST /v1/containers/{container_uuid}/secrets

Add a secret to an existing container. This is only supported on generic containers.

### Request Attributes

Name | Type | Description
--- | --- | ---
name | string | (optional) Human readable name for identifying your secret within the container.
secret_ref | uri | (required) Full URI reference to an existing secret.

### Request:

    POST /v1/containers/{container_uuid}/secrets
    Headers:
        X-Project-Id: {project_id}

    Content:
    {
        "name": "private_key",
        "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
    }

### Response:

    {
        "container_ref": "https://{barbican_host}/v1/containers/{container_uuid}"
    }

Note that the requesting ‘container_uuid’ is the same as that provided in the response.

### HTTP Status Codes

In general, error codes produced by the containers POST call pertain here as well, especially in regards to the secret references that can be provided.

Code | Description
--- | ---
201 | Successful update of the container
400 | Missing secret_ref
401 | Invalid X-Auth-Token or the token doesn’t have permissions to this resource
403 | Forbidden. The user has been authenticated, but is not authorized to add the secret to the specified container. This can be based on the user’s role or the project’s quota.

## DELETE /v1/containers/{container_uuid}/secrets

Remove a secret from a container. This is only supported on generic containers.

### Request Attributes

Name | Type | Description
--- | --- | ---
name | string | (optional) Human readable name for identifying your secret within the container.
secret_ref | uri | (required) Full URI reference to an existing secret.

### Request:

    DELETE /v1/containers/{container_uuid}/secrets
    Headers:
        X-Project-Id: {project_id}

    Content:
    {
        "name": "private key",
        "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
    }

### Response:

    204 No Content

### HTTP Status Codes

Code | Description
--- | ---
204 | Successful removal of the secret from the container.
400 | Missing secret_ref
401 | Invalid X-Auth-Token or the token doesn’t have permissions to this resource
403 | Forbidden. The user has been authenticated, but is not authorized to remove the secret from the specified container. This can be based on the user’s role or the project’s quota.
404 | Specified secret_ref is not found in the container.

this page last updated: 2026-04-01 16:51:00

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug