addy · datasets

Secure credentials for your PowerShell scripts

Datasets store credentials and secrets centrally in addy and deliver them as ready-to-use PSCredential objects — no hardcoded passwords in script files, no manual key management.

No account needed to read this page. Register once you’re ready to create your first Dataset. Also see: PowerShell script template

Create free account Browse help center

Core concepts

How Datasets protect your automation

A Dataset is a named secret slot in addy. Scripts request it by name at runtime — the platform handles encryption, key management, and secure delivery.

Secure by design

Values are stored as AES-encrypted SecureStrings. The encryption key is tied to the dataset record in addy — scripts never expose the raw credential in source code or logs.

PSCredential out of the box

get-addydataset returns a PSCredential you can pass directly to Invoke-Command, New-ADUser, Connect-ExchangeOnline, and any other PowerShell command that accepts -Credential.

Central, not local

Rotate a credential in addy once and every script that calls it picks up the new value on its next run — no touching script files, no redeployment, no coordination overhead.

How it works

Three steps from secret to script

Setting up a Dataset takes minutes. Once created, any script with the right public/private key pair can load it.

Create a Dataset in addy

Give the Dataset a name (e.g. svc_addy-AD), enter the credential value, and save. addy encrypts it immediately using AES and stores the SecureString in the dataset record.

Call `get-addydataset` in your script

Pass the Dataset name as -datasetName. The function fetches the encrypted value via the addy REST API using your $publickey and $privatekey, decrypts it with the stored AES key, and wraps the result in a PSCredential.

Use the PSCredential directly

Access the credential object via $ds.credential, or retrieve username and password as plain strings via GetNetworkCredential(). Check $ds.errors first to confirm the load succeeded before using the result.

Code examples

Using `get-addydataset` in practice

The function is included in functions.global.ps1 and available in every admins buddy script after the standard header.

Load credential and access username / password

# Load a dataset by name
$ds = get-addydataset -datasetName "svc_addy-AD" -storeLocally $false -username "svc_addy-AD"

# Always check for errors before using the result
if ($ds.errors -gt 0) {
    Write-Error "Dataset load failed: $($ds.errormessage -join ', ')"
    return
}

# Access as PSCredential (ready for -Credential parameters)
$credential = $ds.credential

# Or retrieve username and password as plain strings
$username = $ds.credential.GetNetworkCredential().username
$password = $ds.credential.GetNetworkCredential().password

Pass PSCredential to PowerShell commands

# The returned PSCredential works directly with any -Credential parameter
$ds = get-addydataset -datasetName "svc_addy-AD" -storeLocally $false

if ($ds.errors -eq 0) {
    # Active Directory
    Get-ADUser -Identity "john.doe" -Credential $ds.credential -Server "dc01.contoso.com"

    # Remote PowerShell session
    $session = New-PSSession -ComputerName "srv01" -Credential $ds.credential
    Invoke-Command -Session $session -ScriptBlock { Get-Service }
    Remove-PSSession $session
}

Plaintext Dataset — API keys and tokens (handling = 2)

# For datasets configured with handling = 2 (plaintext, no SecureString)
# Use this mode for API keys, tokens, and connection strings
$ds = get-addydataset -datasetName "my-api-key" -storeLocally $false

if ($ds.errors -eq 0) {
    $apiKey = $ds.value   # direct plaintext string
    $headers = @{ Authorization = "Bearer $apiKey" }
    Invoke-RestMethod -Uri "https://api.example.com/data" -Headers $headers
}

Reference

Parameters & return values

Full signature of get-addydataset — defined in etc/scripts/functions.global.ps1, line 534.

Input parameters

Parameter	Alias	Required	Default	Description
`-datasetName`	`-keyContext`	Required	—	Name of the Dataset to load. Must match the name set in addy exactly.
`-username`	—	Optional	(datasetName)	Username for the PSCredential object. Falls back to `-datasetName` when not provided.
`-storeLocally`	`-securestringStoreLocal`	Optional	`$false`	Cache the AES-encrypted SecureString to disk under `C:\addy\SecureStrings\`. Speeds up repeated loads; set `$false` in ephemeral environments.
`-installPath`	—	Optional	`C:\addy\`	Root path of the local addy installation. Used as the base for the `keys\` and `SecureStrings\` subdirectories.

Return object properties

Property	Type	Description
`.credential`	PSCredential	Ready-to-use credential object. Pass as `-Credential $ds.credential` or call `.GetNetworkCredential().username` / `.password` for plain strings.
`.value`	String	Plaintext value. Only populated when the Dataset uses handling = 2 (no SecureString). Use for API keys and tokens.
`.description`	String	Dataset description as entered in addy. Useful for logging and self-documenting scripts.
`.errors`	Int	`0` = success. Any positive value means at least one step failed. Always check this before using `.credential` or `.value`.
`.errormessage`	Array	Array of error message strings. Join with `-join ', '` for clean log output when `.errors > 0`.
`.securestring`	String	AES-encrypted SecureString content as a string. Used internally to sync with addy; rarely needed in script logic.
`.key`	Byte[]	AES key bytes used for encryption and decryption. Persisted locally at the path in `.keypath`.

Related resources

Script template PowerShell script template for admins buddy resources

Copy the header and footer, drop in your automation logic, and turn any script into a ready-to-run admins buddy resource. Includes get-addydataset in the standard header.

Next step

Create your first Dataset

Register for free, set up your first Dataset in addy, and start using get-addydataset in your PowerShell scripts today.

Create free account Get help