# 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

this page last updated: 2026-04-01 16:51:00

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