Application & Process Automation

Getting Started
Authentication & Access
Accounts with Multi-Factor Authentication
Agency and Program Information
Common Usage Scenarios
Create and Submit a Project
Add/Change Data in an Existing Project
Daily Polling for Project Changes
Using Custom IDs
API Method Reference
GetPrograms
URL Format
Response
XML Attributes
Sample Code
GetForms
URL Format
Response
Forms Attributes
AvailableInStatuses and LeadsToStatus
Status Attributes
Sample Code
GetFormSchema
V1 Response
V2 Response
Sample Code
GetProjects
V1 Response
V2 Response
Sample Code
GetProjectsByNumber
V1 Response
V2 Response
Sample Request
Sample Code
GetProjectsByData
Sample Request
Request XML Nodes and Attributes
V1 Response
V2 Response
CreateNewProject
Sample Response
Response XML Attributes
Sample Code
GetAllProjectData - Admin only
Sample Response
XML Attributes
Sample Code
GetProjectData
Sample Response
XML Attributes
Sample Code
SetProjectData
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
GetActiveAttachment
URL Format
Sample Code
GetAttachmentAsAdmin – Admin only
URL Format
SetProjectAttachment
Identifying attachment file types
URL Format
Sample Response
Response XML Attributes
Sample Code
SetAttachmentMetadata
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
GetAttachmentMetadata
URL Format
Sample Response
Response XML Attributes
Sample Code
SubmitProject
URL Format
Sample Response
Response XML Attributes
Sample Code
GetStatusList – Admin only
Sample Code
URL Format
Sample Response
Response XML Attributes
GetCustomListChoices
URL Format
Sample Response
Response XML Attributes
GetProjectStatusHistory – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
SetProjectStatus – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
GetExportProject – Admin only
Response XML Attributes
Sample Code
URL Format
Sample Response
CreateMfaSessionToken
URL Format
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
DeleteMfaSessionToken
URL Format
Sample Response
Sample Code
Code Samples
EncodeAuthorizationHeader
MakeGetRequest
MakePostRequest
MakeGetFileRequest
MakeDeleteRequest
PowerShell

CreateMfaSessionToken

Creates a new Multi-Factor Authentication Session Token (MST). Users with Multi-Factor Authentication (MFA) enabled on their accounts must provide either a valid MST or a valid Time-based-One-Time-Password (TOTP) from their authenticator application in order to make any API request. In order to make this request, the user must have MFA enabled on their account and must provide a TOTP as described in “Authentication & Access”. Note that this is the one request for which a TOTP is the only valid second authentication factor; that is, you cannot use an existing MST as authentication to create a new MST. When you create a new MST, any existing MST will be deleted.
 
HTTP verb: Post
Required inputs: None

URL Format

Format: https://{BaseURL}/Accounts/MfaSessionTokens
 
Sample: https://{BaseURL}/Accounts/MfaSessionTokens

Sample Request


<?xml version="1.0"?>
<CreateMfaSessionTokenRequest ExpiresAfterMinutes="60" />
<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://service.powerclerk.com/api/v1/">
  <xs:element name="CreateMfaSessionTokenRequest">
    <xs:complexType>
      <xs:attribute name="ExpiresAfterMinutes" type="xs:float" use="required" />
    </xs:complexType>
  </xs:element>
</xs:schema>

Request XML Attributes

<CreateMfaSessionTokenRequest> Attributes
 
ExpiresAfterMinutes – Required. The number of minutes after creation when the MST will expire. Must be between 0 and 1440 (1 day).

Sample Response


<CreateMfaSessionTokenResponse>
    <MfaSessionToken 
        TokenValue="ec89e8da-bcd5-46ae-84c9-eef928878230" 
        ExpirationTimeUtc="2019-04-23T21:24:52.2841505+00:00" 
        TokenId="V1YQV0D01MXW" />
</CreateMfaSessionTokenResponse>

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://service.powerclerk.com/api/v1/">
  <xs:element name="CreateMfaSessionTokenResponse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="MfaSessionToken">
          <xs:complexType>
            <xs:attribute name="TokenValue" type="xs:string" use="required" />
            <xs:attribute name="ExpirationTimeUtc" type="xs:dateTime" use="required" />
            <xs:attribute name="TokenId" type="xs:string" use="required" />
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute type="xs:float" name="SchemaVersion"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Response XML Attributes

<MfaSessionToken> Attributes
 
TokenValue – The value of the generated token. This is the value you should pass in the Mfa-Session-Token header when using the MST to authenticate in the PowerClerk API.
ExpirationTimeUtc – The expiration timestamp of the generated token in UTC time.
TokenId – The public ID of the generated token. This is how you will refer to the MST if you want to delete it via the DeleteMfaSessionToken API.

Sample Code


// Create an MFA Session Token for the user with the given username,
// password, and apiKey that expires in "expiresAfterMinutes" minutes
// after creation.
public Tuple<string, string, string> CreateMfaSessionToken(
    string username, 
    string password, 
    string apiKey,
    int expiresAfterMinutes)
{
    // Create an XML request payload that creates an MFA Session Token for
    // use with MFA-enabled PowerClerk account API requests
    XNamespace ns = "http://service.powerclerk.com/api/v1/";
    XDocument xDocument = new XDocument(
        new XElement(ns + "CreateMfaSessionTokenRequest",
            new XAttribute("ExpiresAfterMinutes", expiresAfterMinutes)));

    XmlDocument requestPayload = new XmlDocument();
    using (XmlReader xmlReader = xDocument.CreateReader())
    {
        requestPayload.Load(xmlReader);
    }

    // Generate url and execute request with the XML payload we created earlier
    string url = "/Accounts/MfaSessionTokens";
    XDocument xmlResponse =
        MakePostRequest(BaseUrl + url, username, password, apiKey, requestPayload);

    XElement tokenElement = xmlResponse.Descendants(ns + "MfaSessionToken").ToList()[0];

    string tokenId = tokenElement.Attribute("TokenId").Value;
    string tokenValue = tokenElement.Attribute("TokenValue").Value;
    string expirationTimeUtc = tokenElement.Attribute("ExpirationTimeUtc").Value;
    
    return new Tuple<string,string,string>(tokenId, tokenValue, expirationTimeUtc);
}

See Chapter Code Samples for MakePostRequest sample code.

What’s Next?