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 get the secret details to view the 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 equal to this value. |
bits | integer | Selects all secrets with bit_length equal to this value. |
alg | string | Selects all secrets with algorithm equal to this value. |
mode | string | Selects all secrets with mode equal to this value. |
Response Attributes¶
Name | Type | Description |
---|---|---|
secrets | list | Contains a list of dictionaries filled with secret metadata. |
total | integer | The total number of secrets available to the user. |
next | string | A HATEOS 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 HATEOS 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
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 timestamp in ISO 8601
format YYYY-MM-DDTHH:MM:SSZ . Once this
time has past, the secret will no longer be
available. |
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 provided. |
None |
payload_content_type | string | (optional) (required if payload is added)
The type and format of the secret data. The
two supported types are text/plain and
application/octet-stream . |
None |
payload_content_encoding | string | (optional) The encoding used to format the payload provided. Currently only base64 is supported. This is required if content type provided has an encoding available. | None |
secret_type | string | (optional) Used to indicate the type of
secret being stored. If no value is given,
opaque is used as the default, which is
used to signal Barbican to just store the
information without worrying about format or
encoding. |
opaque |
Request:¶
POST /v1/secrets
Headers:
Content-Type: application/json
X-Project-Id: {project_id}
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 |
415 | Unsupported media-type |
GET /v1/secrets/{uuid}¶
Retrieves a secret’s metadata or payload via uuid.
The return type of content, metadata or payload, is controlled by the Accept header.
Accept Header Options:¶
- application/json - Returns secret metadata
- application/octet-stream - Returns secret payload
- text/plain - Returns secret payload
Metadata Request:¶
GET /v1/secrets/{uuid}
Headers:
Accept: application/json
X-Project-Id: {project_id}
Metadata 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:¶
GET /v1/secrets/{uuid}
Headers:
Accept: application/octet-stream
X-Project-Id: {project_id}
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}¶
Update a secret’s payload by uuid
Note
This action can only be done for a secret that doesn’t have a payload already set.
Required Headers¶
Name | Description | Default |
---|---|---|
Content-Type | Corresponds with the payload_content_type attribute of a normal secret creation request. | text/plain |
Content-Encoding | Corresponds with the payload_content_encoding attribute of a normal secret creation request. | None |
Request:¶
PUT /v1/secrets/{uuid}
Headers:
X-Project-Id: {project_id}
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-Project-Id: {project_id}
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:¶
- application/octet-stream - Returns secret payload
- text/plain - Returns secret payload
Request:¶
GET /v1/secrets/{uuid}/payload
Headers:
Accept: text/plain
X-Project-Id: {project_id}
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 |