POST Extensions Scripts

The POST /Extensions/Scripts operation adds a new script to the database. Scripts are used for certificate requests, SSHClosed The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. alerts, and workflows, and are stored in the Keyfactor Command database to ensure they are securely managed and accessed only with appropriate permissions. On success, the operation returns HTTP 200 OK with  details of the newly created script record.

Important:  This is the only means to add a script to the database. There is no Management Portal equivalent for security reasons. When upgrading from versions earlier than version 11, existing scripts are automatically imported into the database.
Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/scripts/modify/

Table 534: POST Extensions Scripts Input Parameters

Name In Description
Name Body Required.  A string indicating the user-defined name of the script. The name of a script cannot be changed once posted.

Contents

 Body

Required. A JSON-escaped string containing the contents of the script on a single line.

Tip:  See below for examples of creating and handling this string.
Categories Body

Required.  An array of either integers or case-sensitive strings indicating which category or categories the script applies to. The category of a script cannot be changed if it is in use in any alerts or workflows of that category. ClosedShow possible category values.

Example:  Two Approaches to Importing Scripts to the Database

To create a string value for the Contents field, convert the script to a string and JSON-escape it. This encodes characters such as CR/LF and tabs and ensures the string appears on a single line. For example, the following string contains escaped CR/LFs (\r\n):

$MyVar = \"Hello, World!\"\r\n\r\nWrite-Host $MyVar

One approach to doing this uses a PowerShell script similar to the following, which takes the script to be uploaded as input and creates an output file with the JSON-escaped string:

Copy 
# Path to the input file
$filePath = "C:\Stuff\UpdateSubjectSANs.ps1"

# Get the contents of the input file as a string (as opposed to an array of strings) into a variable
$fileContent = Get-Content -Path $filePath -Raw

# Set variables for the other body parameters - for multiple categories, use commas (for example, 2,3,4)
$ScriptName = "UpdateSubjectSANs"
[int32[]]$Categories = 6 

# Build the body
$body = @{
   "Name" = $ScriptName
   "Contents" = $fileContent.ToString()
   "Categories" = $Categories
}

# JSON escape the body elements
$JSONbody = ConvertTo-JSON $body

# Output the body elements including the escaped Contents string to a file
Set-Content -Value $JSONbody -Path C:\Stuff\MyOutFile.txt

The contents of the output file will look something like (the Contents field is shown truncated here):

Copy 
{
   "Categories":  [
      6
   ],
   "Contents":  "# Declare your parameters at the beginning ($CSRSubject, $CSRSANs)\r\nparam(\r\n   [string]$CSRSubject,\r\n   [string]$CSRSANs,\r\n",
   "Name":  "UpdateSubjectSANs"
}

You can then open the output file, display the content without line wrapping the Contents field, and copy either the entire body or the JSON-escaped Contents string for pasting into your APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. command. Any line wraps that display on the screen in the Contents field will be interpreted by copy/paste as CR/LF, which will cause the API command to fail. If your script is long, be sure to use a text editor to open the file that can display the entire length of the Contents string as a single line. The built-in Windows Notepad application will display a maximum of 1024 characters on a line before wrapping even if word wrap is turned off. Third-party tools can be less limited.

Alternately, you can do the JSON-escaping and update to the Keyfactor Command database in a single PowerShell script and skip the file output with copy/paste. The following script will JSON-escape a script and add it to the database:

Copy 
# Prompt for credentials to authenticate to the Keyfactor API
$cred = Get-Credential

# Encode credentials (assumes the Keyfactor API is using Basic authentication)
$pair = "$($cred.Username):$($cred.GetNetworkCredential().Password)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

# Path to the input file
$filePath = "C:\Stuff\UpdateSubjectSANs.ps1"

# Keyfactor Command server name and optional port for API request
$APIServer = "keyfactor.keyexample.com"

# Set variables for the other body parameters - for multiple categories, use commas (for example, 2,3,4)
$ScriptName = "UpdateSubjectSANs"
[int32[]]$Categories = 6

# Get the contents of the input file as a string (as opposed to an array of strings) into a variable
$fileContent = Get-Content -Path $filePath -Raw

# Build the headers
$headers = @{
   "Authorization"=$basicAuthValue
   "Accept"="application/json"
   "x-keyfactor-requested-with"="APIClient"
}

# Build the body
$body = @{
   "Name" = $ScriptName
   "Contents" = $fileContent.ToString()
   "Categories" = $Categories
}

# Make the API request to create a new script in the database
Invoke-WebRequest -Uri "https://$APIServer/KeyfactorAPI/Extensions/Scripts" -Method:Post -Headers $headers -ContentType "application/json" -Body ($body|ConvertTo-Json) -ErrorAction:Stop -TimeoutSec 60

Table 535: POST Extensions Scripts Response Data

Name Description
id An integer indicating the Keyfactor Command reference ID for the script.
Name A string indicating the user-defined name of the script. The name of a script cannot be changed once posted.

Contents

A JSON-escaped string containing the contents of the script on a single line.
Categories

An array of either integers or case-sensitive strings indicating which category or categories the script applies to. The category of a script cannot be changed if it is in use in any alerts or workflows of that category. ClosedShow possible category values.
Tip:  See the Keyfactor API Reference and Utility, which allows you to call API operations and view results. It is primarily intended for validation, testing, and workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. development, and also serves as an interactive supplement to this API documentation. You can access it from the help menu () in the Management Portal.