Secret Metadata API - Reference

GET /v1/secrets/{uuid}/metadata

Lists a secret’s user-defined metadata.

If a secret does not contain any user metadata, an empty list will be returned.

Request:

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

Response:

{
  'metadata': {
    'description': 'contains the AES key',
    'geolocation': '12.3456, -98.7654'
    }
}

Response Attributes

Name Type Description
metadata list Contains a list of the secret metadata’s key/value pairs. The provided keys must be lowercase. If not they will be converted to lowercase.

HTTP Status Codes

Code Description
200 Successful Request
401 Invalid X-Auth-Token or the token doesn’t have permissions to access this resource.
403 Forbidden. The user has been authenticated, but is not authorized to retrieve secret metadata. This can be based on the user’s role.
404 Not Found

PUT /v1/secrets/{uuid}/metadata

Sets the metadata for a secret. Any metadata that was previously set will be deleted and replaced with this metadata.

Parameters

Name Type Description
metadata list Contains a list of the secret metadata’s key/value pairs. The provided keys must be lowercase. If not they will be converted to lowercase.

Request:

PUT /v1/secrets/{uuid}/metadata
Headers:
    Content-Type: application/json
    X-Auth-Token: <token>

Content:
{
  'metadata': {
      'description': 'contains the AES key',
      'geolocation': '12.3456, -98.7654'
    }
}

Response:

201 OK
{
    "metadata_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}/metadata"
}

HTTP Status Codes

Code Description
201 Successfully created/updated Secret Metadata
400 Bad Request
401 Invalid X-Auth-Token or the token doesn’t have permissions to access this resource.
403 Forbidden. The user has been authenticated, but is not authorized to create secret metadata. This can be based on the user’s role.

GET /v1/secrets/{uuid}/metadata/{key}

Retrieves a secret’s user-added metadata.

Request:

GET /v1/secrets/{uuid}/metadata/{key}
Headers:
    Accept: application/json
    X-Auth-Token: <token>

Response:

200 OK
{
  "key": "access-limit",
  "value": "0"
}

HTTP Status Codes

Code Description
200 Successful request
401 Invalid X-Auth-Token or the token doesn’t have permissions to access this resource
403 Forbidden. The user has been authenticated, but is not authorized to retrieve secret metadata. This can be based on the user’s role.
404 Not Found

POST /v1/secrets/{uuid}/metadata/

Adds a new key/value pair to the secret’s user metadata. The key sent in the request must not already exist in the metadata. The key must also be in lowercase, otherwise it will automatically be changed to lowercase.

Request:

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

Content:
  {
    "key": "access-limit",
    "value": "11"
  }

Response:

201 Created
Secret Metadata Location: http://example.com:9311/v1/secrets/{uuid}/metadata/access-limit
  {
    "key": "access-limit",
    "value": "11"
  }

HTTP Status Codes

Code Description
201 Successful request
400 Bad Request
401 Invalid X-Auth-Token or the token doesn’t have permissions to access this resource.
403 Forbidden. The user has been authenticated, but is not authorized to create secret metadata. This can be based on the user’s role.
409 Conflict. The provided metadata key already exists.

PUT /v1/secrets/{uuid}/metadata/{key}

Updates an existing key/value pair in the secret’s user metadata. The key sent in the request must already exist in the metadata. The key must also be in lowercase, otherwise it will automatically be changed to lowercase.

Request:

PUT /v1/secrets/{uuid}/metadata/{key}
Headers:
    X-Auth-Token: <token>
    Content-Type: application/json

Content:
  {
    "key": "access-limit",
    "value": "11"
  }

Response:

200 OK

{
  "key": "access-limit",
  "value": "11"
}

HTTP Status Codes

Code Description
200 Successful request
400 Bad Request
401 Invalid X-Auth-Token or the token doesn’t have permissions to access this resource.
403 Forbidden. The user has been authenticated, but is not authorized to update secret metadata. This can be based on the user’s role.
404 Not Found

DELETE /v1/secrets/{uuid}/metadata/{key}

Delete secret metadata by key.

Request:

DELETE /v1/secrets/{uuid}/metadata/{key}
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 access this resource.
403 Forbidden. The user has been authenticated, but is not authorized to delete secret metdata. This can be based on the user’s role.
404 Not Found