3c935a82d1
This is the start of a reworking of our docs around the secrets API. There will be a number of follow-up patches before this document will be considered complete. Until this document is considered complete, I'm not adding this page to the table of contents. Also, to limit individual CR size, I've tossed TODOs on the areas that will be worked on in future CRs. Change-Id: I8599628d51f4b5aae9ec1b8fd76f419d5b38bdcc
8.1 KiB
8.1 KiB
Secrets API - Reference
GET /secrets
Lists a project's secrets.
The list of secrets can be filtered by the parameters passed in via the URL.
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 /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. |
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. | 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 |
TODO(jvrbanac): Finish this section
GET /secrets/{uuid}
Retrieves a secret's metadata by uuid
TODO(jvrbanac): Finish this section
DELETE /secrets/{uuid}
Delete a secret by uuid
TODO(jvrbanac): Finish this section
GET /secrets/{uuid}/payload
Retrieve a secret's payload
TODO(jvrbanac): Finish this section
PUT /secrets/{uuid}/payload
Update a secret's payload
TODO(jvrbanac): Finish this section