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 metadata. This can be based on the user’s role.

404

Not Found