Credential Vault

The Credential Vault stores reusable Local and Domain accounts so that remote commands and software deployments can run as an alternate user instead of the SYSTEM account. Passwords are encrypted on the server with AES-256-GCM and are never returned by the API — you reference a saved credential by its ID, and the server decrypts it only at execution time. Manage the vault from the console, the REST API, or the PowerShell module.

What a credential is#

Each vault entry has a unique name, a username, a password, and a credential type. The type controls how the account is presented:

Alongside those fields, each credential tracks an optional description, an active flag, who created and last modified it and when, and usage telemetry — a usage count and a last-used timestamp that are updated every time the credential is applied. Names must be unique: creating or renaming to a name that already exists is rejected.

Who can use it#

The Credentials API requires the Operator or Admin role to read, and the Admin role to make changes:

Create, update, and delete are written to the audit log; a password change is recorded as part of the update event. See Roles & Permissions for the full role model.

How passwords are protected#

Passwords are encrypted with AES-256-GCM (a 96-bit random nonce and a 128-bit authentication tag per value). The AES-256 key is derived with HKDF-SHA256 from the server's root CA private key — the same PKI that signs agent certificates — so the vault is bound to that specific server's key material and needs no separate password to unlock.

Stored passwords never leave the server in plaintext through the API. Every read endpoint returns the credential's metadata only — the password field is omitted entirely. The server decrypts a password solely to hand it to an agent at execution time, and only for an active credential.

Running as a stored credential#

A remote command runs either as SYSTEM or as a stored credential. When you choose a stored credential, set the command's runAsSystem to false and provide the credential's credentialId. At execute time the server looks up the credential, decrypts it, and passes the username, password, and domain to the agent; it also increments that credential's usage count.

The same RunAs choice applies to deployment packages: a package runs as SYSTEM by default, or as a specific credential when you set its run-as option to use a credential and supply the credentialId. Use the lightweight selection endpoint (below) to populate a credential picker in your own tooling.

REST API#

All endpoints are rooted at api/credentials and return the standard API envelope.

POST /api/credentials
{
  "name": "DomainAdmin",
  "description": "Domain admin account for deployments",
  "username": "admin",
  "domain": "CONTOSO",
  "password": "••••••••",
  "credentialType": 1
}

credentialType is 0 for Local and 1 for Domain. On success the created credential is returned (without the password) with a 201 Created. To rotate a password later, send just that field:

PUT /api/credentials/{id}
{
  "password": "••••••••"
}

# Deactivate without deleting
PUT /api/credentials/{id}
{
  "isActive": false
}

Deactivating a credential (isActive = false) keeps it in the vault but hides it from the default list and the selection endpoint, and stops it from being used at execution time — a safer alternative to deletion when you want to retire an account but keep its history.

PowerShell#

The Athena PowerShell module ships four credential cmdlets. Passwords are passed as a SecureString, so they are never typed in clear text on the command line:

# Create a local admin credential
New-AthenaCredential -Name "LocalAdmin" `
    -Username "Administrator" `
    -Password (Read-Host -AsSecureString "Password") `
    -CredentialType Local

# Create a domain credential with a description
New-AthenaCredential -Name "DomainAdmin" `
    -Username "admin" -Domain "CONTOSO" `
    -Password (Read-Host -AsSecureString "Password") `
    -CredentialType Domain -Description "For deployments"

# List credentials (passwords are never returned)
Get-AthenaCredential
Get-AthenaCredential -IncludeInactive
Get-AthenaCredential -ForSelect            # lightweight picker list

# Rotate a password, then deactivate
Set-AthenaCredential -Id $credId -Password (Read-Host -AsSecureString "New password")
Set-AthenaCredential -Id $credId -IsActive $false

# Permanently delete (prompts — ConfirmImpact is High)
Remove-AthenaCredential -Id $credId