> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/privileged-access-manager/universal-secrets-sync/advanced.md).

# Advanced

This page outlines some of the more advanced behavior of USS across AWS, Azure, and Google Cloud. If you are migrating existing cloud secrets into Keeper first, see the [Migration Guide](/keeperpam/privileged-access-manager/universal-secrets-sync/migration.md).  You may also want to review the [basics](/keeperpam/privileged-access-manager/universal-secrets-sync/setup.md).

### Secret Name Format: Record Title <a href="#secret-naming-rules" id="secret-naming-rules"></a>

Cloud secret names are based on Keeper record titles and are validated and converted according to each provider's naming requirements.  If a record's title is change then a new secret will be created with the corresponding name.

### Secret Naming Rules <a href="#secret-naming-rules" id="secret-naming-rules"></a>

#### AWS Secrets Manager <a href="#aws-secrets-manager-1" id="aws-secrets-manager-1"></a>

* **Length**: 1-512 characters
* **Allowed**: Alphanumeric + `/_+=.@-`
* **Conversion**: Spaces → hyphens
* **Example**: "My Secret" → "My-Secret"

#### Azure Key Vault <a href="#azure-key-vault-1" id="azure-key-vault-1"></a>

* **Length**: 1-127 characters
* **Allowed**: Alphanumeric + hyphens
* **Must start**: With a letter
* **Must end**: With letter or digit
* **Conversion**: Spaces → hyphens
* **Example**: "My Secret" → "My-Secret"

#### GCP Secret Manager <a href="#gcp-secret-manager" id="gcp-secret-manager"></a>

* **Length**: 1-255 characters
* **Allowed**: Alphanumeric + hyphens + underscores
* **Must start**: With a letter
* **Must end**: With letter, digit, or underscore
* **Conversion**: Spaces → hyphens
* **Example**: "My Secret" → "My-Secret"

***

### Secret Value Format <a href="#secret-value-format" id="secret-value-format"></a>

#### JSON format (default) <a href="#json-format-default" id="json-format-default"></a>

By default, a synced secret's value is a flat JSON document where each key is derived from the Keeper record's field label (falling back to field type).&#x20;

Example — a `login` record synced to AWS:

```json
{"login":"admin","password":"s3cr3t","url":"https://example.com"}
```

#### Plain-text format <a href="#plain-text-format" id="plain-text-format"></a>

When a Keeper record's flattened field set contains **exactly one field named `value`**, the gateway skips JSON serialization and stores the raw field value as a plain string. The cloud secret's ContentType (or equivalent label) is set to `text/plain` instead of `application/json`.

This applies to all three providers automatically — no extra configuration is required.

Here are some examples on how records serialized as plain-text secrets look in Keeper Vault:\
\
![](/files/eOkyLVuWrj7t3buEOx5I) ![](/files/OmltQYCTRY5jdjHSnsOT)

Users can update this secret's value in the Vault UI above and the new value will get synced to the cloud as a plain-text secret, as long as the label isn't modified and additional fields aren't added.

**Example**: a record with a single `value: "my-api-key"` field is stored as:

```
my-api-key
```

rather than:

```json
{"value":"my-api-key"}
```

| Condition                                                      | Stored value                   | ContentType        |
| -------------------------------------------------------------- | ------------------------------ | ------------------ |
| Record has 2+ fields, or the single field is not named `value` | Flat JSON document             | `application/json` |
| Record has exactly one field named `value`                     | Raw field value (plain string) | `text/plain`       |

***

### Metadata and Tags <a href="#metadata-and-tags" id="metadata-and-tags"></a>

Every synced secret is tagged with metadata that identifies its origin and record details. Tags are applied when the secret is first created **and** refreshed on every subsequent sync run (update), so the tags always reflect the current state of the Keeper record.

#### Tag / label reference <a href="#tag--label-reference" id="tag--label-reference"></a>

<table><thead><tr><th width="121.07421875">Purpose</th><th>AWS tag key</th><th>Azure tag key</th><th>GCP label key</th></tr></thead><tbody><tr><td>Content Type</td><td><code>ContentType</code></td><td><em>(content_type field)</em></td><td><code>content_type</code></td></tr><tr><td>Origin</td><td><code>Source</code></td><td><code>Source</code></td><td><code>source</code></td></tr><tr><td>Keeper Record Title</td><td><code>keeper_RecordTitle</code></td><td><code>keeper_RecordTitle</code></td><td><code>keeper_recordtitle</code></td></tr><tr><td>Keeper Record Type</td><td><code>keeper_RecordType</code></td><td><code>keeper_RecordType</code></td><td><code>keeper_recordtype</code></td></tr><tr><td>Keeper Record UID</td><td><code>keeper_RecordUID</code></td><td><code>keeper_RecordUID</code></td><td><code>keeper_recorduid</code></td></tr></tbody></table>

**ContentType values**:

| Secret format                     | AWS / Azure value  | GCP label value    |
| --------------------------------- | ------------------ | ------------------ |
| JSON (default)                    | `application/json` | `application_json` |
| Plain text (single `value` field) | `text/plain`       | `text_plain`       |

> **GCP note**: GCP label keys and values must be lowercase. The `keeper_recordtitle` value is sanitized to lowercase with hyphens (e.g. "My Secret" → `my-secret`). The `keeper_recordtype` value is lowercased similarly (e.g. `login`, `custom_myorgtype`). The `keeper_recorduid` value is sanitized the same way. ContentType values follow the same rule: `application/json` → `application_json`, `text/plain` → `text_plain`.

**`keeper_RecordType` values**

Built-in Keeper record types (e.g. `login`, `bankAccount`, `pamMachine`, `pamAwsConfiguration`) are stored verbatim. User-defined custom record types are prefixed with `custom_` so consumers can distinguish them:

| Record type          | Tag value          |
| -------------------- | ------------------ |
| `login`              | `login`            |
| `pamUser`            | `pamUser`          |
| `myOrgType` (custom) | `custom_myOrgType` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.keeper.io/keeperpam/privileged-access-manager/universal-secrets-sync/advanced.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.