Secrets API - Reference

updated: 2019-04-10 01:04

Secrets API - Reference

GET /v1/secrets

Lists a project’s secrets.

The list of secrets can be filtered by the parameters passed in via the URL.

The actual secret payload data will not be listed here. Clients must instead make a separate call to retrieve the secret payload data for each individual secret.

Parameters

Name Type Description
offset integer The starting index within the total list of the secrets that you would like to retrieve.
limit integer The maximum number of records to return (up to 100). The default limit is 10.
name string Selects all secrets with name similar to this value.
alg string Selects all secrets with algorithm similar to this value.
mode string Selects all secrets with mode similar to this value.
bits integer Selects all secrets with bit_length equal to this value.
secret_type string Selects all secrets with secret_type equal to this value.
acl_only boolean Selects all secrets with an ACL that contains the user. Project scope is ignored.
created string Date filter to select all secrets with created matching the specified criteria. See Date Filters below for more detail.
updated string Date filter to select all secrets with updated matching the specified criteria. See Date Filters below for more detail.
expiration string Date filter to select all secrets with expiration matching the specified criteria. See Date Filters below for more detail.
sort string Determines the sorted order of the returned list. See Sorting below for more detail.

Date Filters:

The values for the created, updated, and expiration parameters are comma-separated lists of time stamps in ISO 8601 format. The time stamps can be prefixed with any of these comparison operators: gt: (greater-than), gte: (greater-than-or-equal), lt: (less-than), lte: (less-than-or-equal).

For example, to get a list of secrets that will expire in January of 2020:

GET /v1/secrets?expiration=gte:2020-01-01T00:00:00,lt:2020-02-01T00:00:00

Sorting:

The value of the sort parameter is a comma-separated list of sort keys. Supported sort keys include created, expiration, mode, name, secret_type, status, and updated.

Each sort key may also include a direction. Supported directions are :asc for ascending and :desc for descending. The service will use :asc for every key that does not include a direction.

For example, to sort the list from most recently created to oldest:

GET /v1/secrets?sort=created:desc

Request:

GET /v1/secrets?offset=1&limit=2&sort=created
Headers:
    Accept: application/json
    X-Auth-Token: {keystone_token}
    (or X-Project-Id: {project id})

Response:

{
    "next": "http://{barbican_host}:9311/v1/secrets?limit=2&offset=3",
    "previous": "http://{barbican_host}:9311/v1/secrets?limit=2&offset=0",
    "secrets": [
        {
            "algorithm": null,
            "bit_length": null,
            "content_types": {
                "default": "application/octet-stream"
            },
            "created": "2015-04-07T03:37:19.805835",
            "creator_id": "3a7e3d2421384f56a8fb6cf082a8efab",
            "expiration": null,
            "mode": null,
            "name": "opaque octet-stream base64",
            "secret_ref": "http://{barbican_host}:9311/v1/secrets/{uuid}",
            "secret_type": "opaque",
            "status": "ACTIVE",
            "updated": "2015-04-07T03:37:19.808337"
        },
        {
            "algorithm": null,
            "bit_length": null,
            "content_types": {
                "default": "application/octet-stream"
            },
            "created": "2015-04-07T03:41:02.184159",
            "creator_id": "3a7e3d2421384f56a8fb6cf082a8efab",
            "expiration": null,
            "mode": null,
            "name": "opaque random octet-stream base64",
            "secret_ref": "http://{barbican_host}:9311/v1/secrets/{uuid}",
            "secret_type": "opaque",
            "status": "ACTIVE",
            "updated": "2015-04-07T03:41:02.187823"
        }
    ],
    "total": 5
}

Response Attributes

Name Type Description
secrets list Contains a list of secrets. The attributes in the secret objects are the same as for an individual secret.
total integer The total number of secrets available to the user.
next string A HATEOAS URL to retrieve the next set of secrets based on the offset and limit parameters. This attribute is only available when the total number of secrets is greater than offset and limit parameter combined.
previous string A HATEOAS URL to retrieve the previous set of secrets based on the offset and limit parameters. This attribute is only available when the request offset is greater than 0.

HTTP Status Codes

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

POST /v1/secrets

Creates a Secret entity. If the payload attribute is not included in the request, then only the metadata for the secret is created, and a subsequent PUT request is required.

Attributes

Attribute Name Type Description Default
name string (optional) The name of the secret set by the user. None
expiration string (optional) This is a UTC timestamp in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ. If set, the secret will not be available after this time. None
algorithm string (optional) Metadata provided by a user or system for informational purposes. None
bit_length integer (optional) Metadata provided by a user or system for informational purposes. Value must be greater than zero. None
mode string (optional) Metadata provided by a user or system for informational purposes. None
payload string (optional) The secret’s data to be stored. payload_content_type must also be supplied if payload is included. None
payload_content_type string (optional) (required if payload is included) The media type for the content of the payload. For more information see Secret Types None
payload_content_encoding string (optional) (required if payload is encoded) The encoding used for the payload to be able to include it in the JSON request. Currently only base64 is supported. None
secret_type string (optional) Used to indicate the type of secret being stored. For more information see Secret Types opaque

Request:

POST /v1/secrets
Headers:
    Content-Type: application/json
    X-Auth-Token: <token>

Content:
{
    "name": "AES key",
    "expiration": "2015-12-28T19:14:44.180394",
    "algorithm": "aes",
    "bit_length": 256,
    "mode": "cbc",
    "payload": "YmVlcg==",
    "payload_content_type": "application/octet-stream",
    "payload_content_encoding": "base64"
}

Response:

201 Created

{
    "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
}

HTTP Status Codes

Code Description
201 Successfully created a Secret
400 Bad Request
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 secret. This can be based on the user’s role or the project’s quota.
415 Unsupported media-type

GET /v1/secrets/{uuid}

Retrieves a secret’s metadata.

Request:

GET /v1/secrets/{uuid}
Headers:
    Accept: application/json
    X-Auth-Token: {token}
    (or X-Project-Id: {project_id})

Response:

200 OK

{
    "status": "ACTIVE",
    "created": "2015-03-23T20:46:51.650515",
    "updated": "2015-03-23T20:46:51.654116",
    "expiration": "2015-12-28T19:14:44.180394",
    "algorithm": "aes",
    "bit_length": 256,
    "mode": "cbc",
    "name": "AES key",
    "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}",
    "secret_type": "opaque",
    "content_types": {
        "default": "application/octet-stream"
    }
}

Payload Request:

Warning

DEPRECATION WARNING: Previous releases of the API allowed the payload to be retrieved from this same endpoint by changing the Accept header to be one of the values listed in the content_types attribute of the Secret metadata. This was found to be problematic in some situations, so new applications should make use of the /v1/secrets/{uuid}/payload endpoint instead.

GET /v1/secrets/{uuid}
Headers:
    Accept: application/octet-stream
    X-Auth-Token: <token>

Payload Response:

200 OK

beer

HTTP Status Codes

Code Description
200 Successful request
401 Invalid X-Auth-Token or the token doesn’t have permissions to this resource
404 Not Found
406 Not Acceptable

PUT /v1/secrets/{uuid}

Add the payload to an existing metadata-only secret, such as one made by sending a POST /v1/secrets request that does not include the payload attribute.

Note

This action can only be done for a secret that doesn’t have a payload.

Headers

Name Description Default
Content-Type Corresponds with the payload_content_type attribute of a normal secret creation request. text/plain
Content-Encoding (optional) Corresponds with the payload_content_encoding attribute of a normal secret creation request. None

Request:

PUT /v1/secrets/{uuid}
Headers:
    X-Auth-Token: <token>
    Content-Type: application/octet-stream
    Content-Encoding: base64

Content:
YmxhaA==

Response:

204 No Content

HTTP Status Codes

Code Description
204 Successful request
401 Invalid X-Auth-Token or the token doesn’t have permissions to this resource
404 Not Found

DELETE /v1/secrets/{uuid}

Delete a secret by uuid

Request:

DELETE /v1/secrets/{uuid}
Headers:
    X-Auth-Token: <token>

Response:

204 No Content

HTTP Status Codes

Code Description
204 Successful request
401 Invalid X-Auth-Token or the token doesn’t have permissions to this resource
404 Not Found

GET /v1/secrets/{uuid}/payload

Retrieve a secret’s payload

Accept Header Options:

When making a request for a secret’s payload, you must set the accept header to one of the values listed in the content_types attribute of a secret’s metadata.

Request:

GET /v1/secrets/{uuid}/payload
Headers:
    Accept: text/plain
    X-Auth-Token: <token>

Response:

200 OK

beer

HTTP Status Codes

Code Description
200 Successful request
401 Invalid X-Auth-Token or the token doesn’t have permissions to this resource
404 Not Found
406 Not Acceptable
updated: 2019-04-10 01:04
Creative Commons Attribution 3.0 License

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 questions?