What is a secret?

Working with secrets of different types

Secrets that you create in Secrets Manager can be static or dynamic in nature. A static secret has its expiration date and time enforced at secret creation or rotation time. In contrast, a dynamic secretA unique value, such as a password or an API key, that is created dynamically and leased to an application that requires access to a protected resource. After a dynamic secret reaches the end of its lease, access to the protected resource is revoked and the secret is deleted automatically. has its expiration date and time enforced when its secret data is read or accessed.

Secrets Manager further classifies static and dynamic secrets by their general purpose or function. For example, each secret type is identified by programmatic name, such as username_password. If you're looking to manage your secret by using the Secrets Manager API or CLI, you can use these programmatic names to run operations on secrets according to their type.

Review the following table to understand the types of static and dynamic secrets that you can create and manage with the service.

*Requires an engine configuration before secrets can be created in the service.

Supported features by secret type

The following table compares and contrasts some common characteristics between the secret types.

Feature comparison between secret types

	Arbitrary secrets	IAM credentials	User credentials	Key-value secrets	Imported certificates	Public certificates	Private certificates	Service credentials	Custom credentials
Automatic rotation		[1]
Manual rotation
Expiry setting
Notifications
Version history
Restore to the previous version
SDK support
CLI plug-in support
HashiCorp Vault HTTP API compatibility

What's in a secret?

Secrets that you store with the service consist of metadata attributes and a secret value. While the metadata attributes help you to identify a secret, the secret value is the data that protected services need to authenticate and authorize you or your application.

Check out the following image to see how a secret is structured.

{
    "name": "my-username-password",
    "id": "cb123456-8e73-4857-594839587438",
    "description": "Description for this secret",
    "secret_type": "username_password",
    "secret_group_id": "ab654321-3958-9484-1395840384754",
    "state": 1,
    "state_description": "Active",
    "create_by": "iam-ServiceId-gj403948-3048-6059-304958674930",
    "created_at": "2023-03-08-T20:44:11Z",
    "labels": [
        "dev",
        "us-south"
    ],
    "username": "user123",
    "password": "cloudy-rainy-coffee-book"
}

1. The name, id, and description, and other common fields hold identifying information about a secret. These fields store the general attributes of your secret that you can use to understand its purpose and history.

2. When you retrieve the value of a secret the fields that are returned differ based on the secret type.

   The following truncated example shows how secret data is represented for an arbitrary secret.

   {
       "name": "my-secret",
       "secret_type": "arbitrary",
       ...
       "payload": "The quick brown fox jumped over the lazy dog."
   }
   

   The following truncated example shows how secret data is represented for a username_password secret.

   {
       "name": "my-secret",
       "secret_type": "username-password",
       ...
       "username": "foo",
       "password": "bar"
   }
   

   The following truncated example shows how secret data is represented for an IAM credential secret.

   {
       "name": "my-iam-credentials",
       "secret_type": "iam_credentials",
       ...
       "api_key": "RmnPBn6n1dzoo0v3kyznKEpg0WzdTpW9lW7FtKa017_u",
       "api_key_id": "ApiKey-dcd0b857-b590-4507-8c64-ae89a23e8d76",
       "service_id": "ServiceId-bb4ccc31-bd31-493a-bb58-52ec399800be",
   }
   

   The following truncated example shows how secret data is represented for a KV secret.

   {
       "name": "my-kv-secret",
       "secret_type": "kv",
       ...
       "data": '{"key":"value"}'
   }
   

   The following truncated example shows how secret data is represented for imported_cert and public_cert secrets.

   {
       "name": "my-certificate",
       "secret_type": "imported_cert/public_cert",
       ...
       "certificate":"...",
       "intermediate":"...",
       "private_key":"..."
   }
   

   The following truncated example shows how secret data is represented for a private_cert secret.

   {
       "name": "my-certificate",
       "secret_type": "private_cert",
       ...
       "certificate":"...",
       "ca_chain":"...",
       "private_key":"..."
   }
   

   The following truncated example shows how secret data is represented for a service_credentials secret.

   {
       "name": "my-secret",
       "secret_type": "service_credential",
       ...
       "credentials": {
           "key": "The quick brown fox jumped over the lazy dog."
           }
   }
   

   The following truncated example shows how secret data is represented for a custom_credentials secret.

   {
       "name": "my-secret",
       "secret_type": "custom_credential",
       ...
       "credentials_content": {
           "key": "The quick brown fox jumped over the lazy dog."
           }
   }
   

Secret states and transitions

Secrets, in their lifetime, transition through several states that are a function of how long the secrets are in existence and whether its associated resources can be accessed.

Secrets Manager provides a graphical user interface and a REST API for tracking secrets as they move through several states in their lifecycle. The following diagram shows how a secret passes through states between its generation and its destruction.

How do I get started?

To get started with secrets, you can go to the Secrets page of the Secrets Manager UI, or check out the API reference to learn more about creating secrets programmatically.