Advanced

Technical details of Universal Secrets Sync

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. You may also want to review the basics.

Secret Name Format: Record Title

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

AWS Secrets Manager

• Length: 1-512 characters

• Allowed: Alphanumeric + /_+=.@-

• Conversion: Spaces → hyphens

• Example: "My Secret" → "My-Secret"

Azure Key Vault

• 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

• 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

JSON format (default)

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).

Example — a login record synced to AWS:

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

Plain-text format

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:

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:

{"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

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

Purpose	AWS tag key	Azure tag key	GCP label key
Content Type	ContentType	(content_type field)	content_type
Origin	Source	Source	source
Keeper Record Title	keeper_RecordTitle	keeper_RecordTitle	keeper_recordtitle
Keeper Record Type	keeper_RecordType	keeper_RecordType	keeper_recordtype
Keeper Record UID	keeper_RecordUID	keeper_RecordUID	keeper_recorduid

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