Office 365 PowerShell queries via REST: Maximizing the Kloudless Pass-through API Vinod Chandru Published: September 28, 2016 In our previous post, we announced the availability of the Kloudless Pass-through API. The Pass-through API enables your application to make API requests directly to third-party services, while still using Kloudless’s unified APIs. In this blog post, we’ll discuss how to access the Office 365 PowerShell via the Kloudless REST API to perform administrative tasks in Office 365.Building with our easy-to-use REST API offers many benefits. We handle the complexities of integrating with each service behind the scenes so you don’t have to. This speeds up your integration time and decreases future maintenance. We’ve extended the same principle to our Pass-through API by introducing special capabilities such as enabling PowerShell queries for Office 365 admin accounts.Office 365 PowerShell provides several remote management commands that can be used to administer your Office 365 tenant, similar to how you would via the Office 365 admin center web application. For example, a broad set of security and compliance features can be accessed via theSecurity & Compliance Center cmdlets by connecting to Office 365 using remote PowerShell. Normally, you would need access to a PowerShell prompt in order to access this functionality. The Kloudless REST API handles the heavy-lifting and enables you to access this functionality via our REST API.Invoking Office 365 Security Center cmdlets via the Kloudless Pass-through APITo begin, connect a SharePoint Online admin account to your Kloudless application. The easiest way to do this is by logging into your Kloudless account and then navigating to the Interactive Docs. Click the “Add Account” button and then click on SharePoint Online under the “Admin accounts” section towards the bottom of the pop-up that opens.Once you’ve connected your account, you will receive a Kloudless Account ID that can be used for API requests to the Kloudless API. You are now ready to make Pass-through API requests to this admin Office 365 account!While SharePoint Online REST API requests can be performed without any additional configuration, the PowerShell queries described in this blog post are available in Kloudless Enterprise and also require special permission to access by Kloudless Enterprise developers. Please contact us at support@kloudless.com to learn how to enable this capability for your Kloudless Enterprise instances.Request FormatThe format of PowerShell pass-through API requests is as follows:URL: https://api.kloudless.com/v1/accounts/{account_id}/raw{account_id} is the Kloudless account ID of the SharePoint Online admin account connected.Headers (described in the Pass-through API docs):X-Kloudless-Raw-URI: http://powershell/ This special value indicates the request should be translated to a PowerShell query.X-Kloudless-Raw-Method: POSTAuthorization: Bearer {account_bearer_token} OR Authorization: APIKey {application_api_key} See our Authentication Docs for more information on authorizing API requests.BodyJSON dataJavaScript { "category": "o365-security", "command": {cmdlet_name}, "options": { ... option name: value mappings if required ... } }1234567{ "category": "o365-security", "command": {cmdlet_name}, "options": { ... option name: value mappings if required ... }}At the current time, only Office 365 Security and Compliance Center cmdlets ("category": "o365-security") and Exchange Online cmdlets ("category": "exchange") are available via the Kloudless API. If you would like access to other remote PowerShell cmdlets, please contact us at support@kloudless.com.Examples of RequestsAn example of a curl request with the format described above would be:Shell curl -H "Authorization: APIKey {api_key}" \ -H "X-Kloudless-Raw-URI: http://powershell/ \ https://api.kloudless.com/v1/accounts/{account_id}/raw \ --data '{body}'1234curl -H "Authorization: APIKey {api_key}" \ -H "X-Kloudless-Raw-URI: http://powershell/ \ https://api.kloudless.com/v1/accounts/{account_id}/raw \ --data '{body}'Please replace the {api_key}, {account_id} and {body} values with your API Key, connected account’s ID and JSON data for PowerShell respectively.Here are some examples of Body data to use in {body} for specific cmdlets:Get-ComplianceCaseObtaining a list of compliance cases. { "category": "o365-security", "command": "Get-ComplianceCase" }1234{ "category": "o365-security", "command": "Get-ComplianceCase"}An example of a curl request for this would be:Get Compliance Case RequestShell curl -H "Authorization: APIKey 123ABC" \ -H "X-Kloudless-Raw-URI: http://powershell/" \ https://api.kloudless.com/v1/accounts/123/raw \ --data '{"category": "o365-security", "command": "Get-ComplianceCase"}'1234curl -H "Authorization: APIKey 123ABC" \ -H "X-Kloudless-Raw-URI: http://powershell/" \ https://api.kloudless.com/v1/accounts/123/raw \ --data '{"category": "o365-security", "command": "Get-ComplianceCase"}'New-ComplianceCaseCreate a new compliance case.New Compliance Case JSONJavaScript { "category": "o365-security", "command": "New-ComplianceCase", "options": { "Name": "test new case 2", "Description": "This case is created via curl" } }12345678{ "category": "o365-security", "command": "New-ComplianceCase", "options": { "Name": "test new case 2", "Description": "This case is created via curl" }}An example curl request would be identical to the one used for Get-ComplianceCase but with the new value above for --data instead.New-CaseHoldPolicyCreate a new hold policy for a case.New Case Hold Policy JSONJavaScript { "category": "o365-security", "command": "New-CaseHoldPolicy", "options": { "Case": "3b4de8d5-13cb-4291-bdd0-b6e2bb82a08e", "Name": "New Hold", "SharePointLocation": "https://kloudless.sharepoint.com/test subsite/" } }123456789{ "category": "o365-security", "command": "New-CaseHoldPolicy", "options": { "Case": "3b4de8d5-13cb-4291-bdd0-b6e2bb82a08e", "Name": "New Hold", "SharePointLocation": "https://kloudless.sharepoint.com/test subsite/" }}where "3b4de8d5-13cb-4291-bdd0-b6e2bb82a08e" is the Identity GUID of the Case to add the legal hold policy to. This corresponds to the Locations section of a Hold when editing a Case’s Holds at https://protection.office.com/#/ediscovery.New-CaseHoldRuleCreate a rule to add to a hold policy.New preservation policy JSONJavaScript { "category": "o365-security", "command": "New-CaseHoldRule", "options": { "Policy": "New Hold", "Name": "New Rule", "ContentMatchQuery": "SSN" } }123456789{ "category": "o365-security", "command": "New-CaseHoldRule", "options": { "Policy": "New Hold", "Name": "New Rule", "ContentMatchQuery": "SSN" }}where "New Hold" is the name of the hold I created previously. This corresponds to the Conditions section of a Hold.Similarly, other policies such as retention policies can also be created, and existing objects can be deleted:New-RetentionCompliancePolicyCreate a new preservation policy.JSON dataJavaScript { "category": "o365-security", "command": "New-RetentionCompliancePolicy", "options": { "Name": "Test new policy", "SharePointLocation": "https://kloudless.sharepoint.com/" } }12345678{ "category": "o365-security", "command": "New-RetentionCompliancePolicy", "options": { "Name": "Test new policy", "SharePointLocation": "https://kloudless.sharepoint.com/" }}This creates a policy but has not yet created a rule to add to it, which can be done with .Remove-ComplianceCaseDeleting a compliance case.Deleting a compliance case JSONJavaScript { "category": "o365-security", "command": "Remove-ComplianceCase", "options": { "Identity": "94b99324-5574-4220-b081-1b689cb386af", "Confirm:$false": null } }12345678{ "category": "o365-security", "command": "Remove-ComplianceCase", "options": { "Identity": "94b99324-5574-4220-b081-1b689cb386af", "Confirm:$false": null }}where "94b99324-5574-4220-b081-1b689cb386af" is the Identity GUID of the Case to remove.Future capabilities of the Pass-through APIThe Pass-through API provides provides a powerful new way to access third-party features via Kloudless as shown above. We’re excited to make this available to all developers on our platform and would love to hear any feedback or suggestions in our developer forum.