Create a Credential : MinionWare

Stores a new credential (a Windows account, a SQL login, an SMTP auth account, or an Azure service principal) that jobs and steps can then be pointed at. The secret is write-only -- it's encrypted on the way in and this API never decrypts or returns it again, to anyone, under any permission. If you need to change it later, you replace it; you can't read it back for comparison.

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

Authenticate to the API.
Send the new credential's details.

The call

POST /api/credentials

Permission needed: Credential.Manage.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Step 2: Send the new credential's details.
var newCredential = new CreateCredentialRequest(
    CredentialName: "SQLPROD02 Service Account",
    CredentialType: "WindowsUser",
    Principal: "CORP\\svc-minionagent2",
    Secret: "the-real-password-goes-here",
    IsElevated: false);
var response = await client.PostAsJsonAsync("/api/credentials", newCredential, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedId>(jsonOptions);
Console.WriteLine($"Created credential id: {created!.CredentialID}");

record CreateCredentialRequest(string CredentialName, string CredentialType, string Principal, string Secret, bool IsElevated = false,
    string? TenantId = null, string? SubscriptionId = null);
record CreatedId(int CredentialID);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2: Send the new credential's details. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newCredential = @{
    CredentialName = "SQLPROD02 Service Account"
    CredentialType = "WindowsUser"
    Principal      = "CORP\svc-minionagent2"
    Secret         = "the-real-password-goes-here"
    IsElevated     = $false
} | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/credentials" `
    -Method Post -Body $newCredential -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Created credential id: $($created.credentialID)"

What you get back

201 Created:

{ "credentialID": 12 }

`CredentialType` values

WindowsUser, SqlLogin, SmtpAuth, or AzureServicePrincipal (case-insensitive). For AzureServicePrincipal, also send TenantId and SubscriptionId. SmtpAuth is used for alert-channel email sending -- see the Alerts category -- it's created through this same endpoint, there's no separate SMTP-only one.

Codes this call can return

See API Response Codes for what each one means in general. For this specific call:

201 -- created.
400 -- CredentialType isn't one of the recognized values.
403 -- you don't have Credential.Manage.

What gets audited

Recorded as Credential / Create Credential, with CredentialName, CredentialType, Principal, and IsElevated in the after-state. The secret is never written to the audit trail, in any form -- not the plain value, not the encrypted bytes.

Create a Credential Print