diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index b541504..8bc99a0 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -1,897 +1,2807 @@ { - "components": { - "parameters": { - "correlationId": { - "description": "The object ID of the correlation identifier for the specified record.", - "in": "path", - "name": "correlationId", - "required": true, - "schema": { - "examples": [ - "1d71e0fe-6e4a-464d-a690-80addf3bda55" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "components": { + "parameters": { + "correlationId": { + "description": "The object ID of the correlation identifier for the specified record.", + "in": "path", + "name": "correlationId", + "required": true, + "schema": { + "examples": ["1d71e0fe-6e4a-464d-a690-80addf3bda55"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "valid correlation Id": { + "summary": "Example valid correlation ID", + "description": "An example of a valid correlation ID in type UUID string.", + "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + } + } + }, + "tenantId": { + "description": "The object ID of the tenant to operate against.", + "in": "path", + "name": "tenantId", + "required": true, + "schema": { + "examples": ["b2fd105a-2594-437e-b934-1a62a51c28b4"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "valid tenant Id": { + "summary": "Example valid tenant ID", + "description": "An example of a valid tenant ID in type UUID string.", + "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + } + } + }, + "channelName": { + "description": "Name of the deploy channel to operate against.", + "in": "path", + "name": "channelName", + "required": true, + "schema": { + "examples": ["beta"], + "type": "string" + }, + "examples": { + "valid channel name": { + "summary": "Example valid channel name", + "description": "An example string of a valid channel name.", + "value": "stable" + } + } + }, + "channelRing": { + "description": "Integer number representing ring to operate against.", + "in": "path", + "name": "number", + "required": true, + "schema": { + "examples": [1], + "type": "integer", + "minimum": 0 + }, + "examples": { + "valid channel ring": { + "summary": "Example valid channel ring", + "description": "An example integer that represents a valid channel ring.", + "value": 1 + }, + "minimum channel ring": { + "summary": "Example minimum channel ring", + "description": "An example integer that represents the minimum valid channel ring.", + "value": 0 + }, + "invalid channel ring": { + "summary": "Example invalid channel ring", + "description": "An example integer that represents an invalid channel ring, which is negative.", + "value": -1 + } + } + }, + "version": { + "description": "Version of the application package.", + "in": "path", + "name": "version", + "required": true, + "schema": { + "examples": ["1.12.5"], + "type": "string" + }, + "examples": { + "Valid version number": { + "summary": "Example valid version number", + "description": "An example string represents a valid semantic version number.", + "value": "1.2.3" + } + } + }, + "parentId": { + "description": "The object ID of the parent value to operate against.", + "in": "query", + "name": "parentId", + "required": false, + "schema": { + "examples": ["3b241101-e2bb-4255-8caf-4136c566a962"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "Valid parent ID": { + "summary": "Example valid parent ID", + "description": "An example UUID string that represents a valid parent object ID.", + "value": "3b241101-e2bb-4255-8caf-4136c566a962" + } + } + }, + "dateStart": { + "description": "Date string to narrow records selection to those created on or after that date.", + "in": "query", + "name": "dateStart", + "required": false, + "schema": { + "examples": ["2025-01-01T00:00:00Z"], + "format": "date-time", + "type": "string" + }, + "examples": { + "Valid start date": { + "summary": "Example valid start date", + "description": "An example ISO8601 date string that represents a valid start date in a query.", + "value": "2025-01-01T00:00:00Z" + } + } + }, + "dateEnd": { + "description": "Date string to narrow records selection to those created before or on that date.", + "in": "query", + "name": "dateEnd", + "required": false, + "schema": { + "examples": ["2025-02-05T23:59:59Z"], + "format": "date-time", + "type": "string" + }, + "examples": { + "Valid end date": { + "summary": "Example valid end date", + "description": "An example ISO8601 date string that represents a valid end date in a query.", + "value": "2025-02-05T23:59:59Z" + } + } + } + }, + "responses": { + "400": { + "description": "Invalid input!" + }, + "401": { + "description": "Principal is not authorized to access this endpoint. Check to make sure the Bearer token is valid and present!" + }, + "403": { + "description": "Principal does not contain the correct scopes (permissions) for the API call that was made, or was made from the wrong tenant. If the permissions were granted, ensure that the access token was requested with the correct scopes." + }, + "404": { + "description": "The requested object was not found." + }, + "503": { + "description": "App is starting still. Feature is not available. Please try again later." + }, + "525": { + "description": "Infrastructure not deployed. Please deploy the infrastructure before using this endpoint." + } + }, + "schemas": { + "Core.HealthReport": { + "description": "Health report that indicates if a service is down or not that the data gateway relies on.", + "properties": { + "authClient": { + "description": "Flag that indicates if the client side authentication validation is working or not.", + "examples": [false], + "type": "boolean" + }, + "authServer": { + "description": "Flag that indicates if the server side authentication is working or not.", + "examples": [true], + "type": "boolean" + }, + "bulkStorage": { + "description": "Flag that indicates if the bulk storage system is down (`false`) or not (`true`). False indicate the service is not working, true indicates the service is working.", + "examples": [true], + "type": "boolean" + }, + "database": { + "description": "Flag that indicates if the ORM (Database) system is down (`false`) or not (`true`). False indicate the service is not working, true indicates the service is working.", + "examples": [false], + "type": "boolean" + } + }, + "required": ["authClient", "authServer", "bulkStorage", "database"], + "title": "Core System - Health Report", + "type": "object", + "examples": [ + { + "authClient": false, + "authServer": true, + "bulkStorage": true, + "database": false + } + ] + }, + "Chat.OpenAIChatMessage": { + "title": "Chat - Message Record", + "description": "Object representing entity supplied to the AI agent or a response from the AI Agent", + "examples": [ + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } + } + ] + }, + { + "name": "John Doe", + "role": "user", + "content": [ + { + "text": "What are the available IDs?", + "type": "text" + } + ], + "tool_call_id": "call_abc123", + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } + } + ] + } + ], + "type": "object", + "properties": { + "content": { + "oneOf": [ + { + "type": "string", + "description": "The contents of the message" + }, + { + "type": "array", + "description": "The contents of the message", + "items": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The text content" + }, + "type": { + "type": "string", + "description": "The type of the content part" + } + }, + "required": ["text", "type"] }, - "examples": { - "valid correlation Id": { - "summary": "Example valid correlation ID", - "description": "An example of a valid correlation ID in type UUID string.", - "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + "examples": [ + [ + { + "text": "What are the available IDs?", + "type": "text" } - } - }, - "tenantId": { - "description": "The object ID of the tenant to operate against.", - "in": "path", - "name": "tenantId", - "required": true, - "schema": { - "examples": [ - "b2fd105a-2594-437e-b934-1a62a51c28b4" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + ] + ] + } + ] + }, + "role": { + "type": "string", + "description": "The role of the messages author", + "examples": ["assistant"] + }, + "name": { + "type": "string", + "description": "An optional name for the participant", + "examples": ["John Doe"] + }, + "tool_calls": { + "type": "array", + "description": "The tool calls generated by the model, such as function calls", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the tool call", + "examples": ["call_abc121"] }, - "examples": { - "valid tenant Id": { - "summary": "Example valid tenant ID", - "description": "An example of a valid tenant ID in type UUID string.", - "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + "function": { + "type": "object", + "description": "The function that the model called", + "properties": { + "arguments": { + "type": "string", + "description": "The arguments to call the function with", + "examples": [ + "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}" + ] + }, + "name": { + "type": "string", + "description": "The name of the function to call", + "examples": ["getCorrelationIDs"] + } + }, + "examples": [ + { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" } + ] + }, + "type": { + "type": "string", + "description": "The type of the tool. Currently, only `function` is supported", + "examples": ["function"] } + }, + "examples": [ + { + "id": "call_abc121", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + }, + "type": "function" + } + ] + } + }, + "tool_call_id": { + "type": "string", + "description": "Tool call that this message is responding to", + "examples": ["call_abc123"] + } + }, + "required": ["content", "role"] + }, + "LicenseReport.CorrelationRecord": { + "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", + "examples": [ + { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", + "reportTenantAccount": "ent-user@example.com", + "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", + "createdAt": "2024-08-01T21:13:12.821Z", + "updatedAt": "2024-08-01T21:13:12.821Z" + } + ], + "properties": { + "auditTenantAccount": { + "description": "The user account used to retrieve the license information in the tenant being audited.", + "examples": ["admin-user@example.com"], + "format": "email", + "type": "string" + }, + "correlationId": { + "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", + "examples": ["88da2253-758f-4135-9d37-64448c8b65c1"], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "reportTenantAccount": { + "description": "User account used to store/report the license report to the SHI Lab cloud service.", + "examples": ["generic-user@example.com"], + "format": "email", + "type": "string" + }, + "tenantId": { + "description": "Unique ID of customer's Microsoft tenant that the license report is for.", + "examples": ["0e1fe83f-a33f-4250-8546-225b8d45ae01"], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "createdAt": { + "description": "Timestamp of when the report was created.", + "examples": ["2024-08-01T21:12:22.148Z"], + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp of when the report was last updated.", + "examples": ["2024-08-01T21:12:22.148Z"], + "format": "date-time", + "type": "string" + } + }, + "required": ["auditTenantAccount"], + "title": "License Report - Correlation Record", + "type": "object" + }, + "LicenseReport.LicenseData": { + "type": "object", + "properties": { + "assignedLicense": { + "additionalProperties": { + "oneOf": [ + { + "type": "integer", + "examples": [0] + }, + { + "type": "null" + } + ] }, - "channelName": { - "description": "Name of the deploy channel to operate against.", - "in": "path", - "name": "channelName", - "required": true, - "schema": { - "examples": [ - "beta" - ], - "type": "string" + "description": "License assignment on the specified principal.", + "type": "object", + "examples": [ + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0 + } + ] + }, + "assignedService": { + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" }, - "examples": { - "valid channel name": { - "summary": "Example valid channel name", - "description": "An example string of a valid channel name.", - "value": "stable" - } + { + "type": "integer", + "format": "int32", + "examples": [0] + }, + { + "type": "null" } + ] }, - "channelRing": { - "description": "Integer number representing ring to operate against.", - "in": "path", - "name": "number", - "required": true, - "schema": { - "examples": [ - 1 - ], - "type": "integer", - "minimum": 0 + "description": "Service configuration assignment. This is used to record the set of principals that are \"benefiting\" from the service, regardless of license status.", + "type": "object", + "examples": [ + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, + "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null + }, + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": false, + "Access Review": true, + "Entitlement Management": false, + "Identity Protection": true + } + } + ] + }, + "consumedService": { + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" }, - "examples": { - "valid channel ring": { - "summary": "Example valid channel ring", - "description": "An example integer that represents a valid channel ring.", - "value": 1 - }, - "minimum channel ring": { - "summary": "Example minimum channel ring", - "description": "An example integer that represents the minimum valid channel ring.", - "value": 0 - }, - "invalid channel ring": { - "summary": "Example invalid channel ring", - "description": "An example integer that represents an invalid channel ring, which is negative.", - "value": -1 - } + { + "type": "integer", + "format": "int32", + "examples": [0] + }, + { + "type": "null" } + ] }, - "version": { - "description": "Version of the application package.", - "in": "path", - "name": "version", - "required": true, - "schema": { - "examples": [ - "1.12.5" - ], - "type": "string" + "description": "Usage telemetry retrieved for the service to indicate if the specific principal is consuming the service or not, regardless of license status.", + "type": "object", + "examples": [ + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": true, + "Access Review": false, + "Entitlement Management": false, + "Identity Protection": true + } + }, + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, + "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null + } + ] + } + }, + "required": ["assignedLicense", "assignedService", "consumedService"], + "description": "Collection of principals that have had their in-use licenses and assigned licenses. Where the key is the principal ID and the value is the insights.", + "examples": [ + { + "assignedLicense": { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 1, + "7159f980-6f83-4b67-bf41-e172b3ae1352": 2 + }, + "assignedService": { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": false, + "Access Review": true, + "Entitlement Management": false, + "Identity Protection": true + }, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { + "Conditional Access": true, + "Dynamic Group": false, + "Group Naming": true, + "On-Prem SSPR": false, + "Group Expiration": true, + "Provisioning Engine": true, + "Enterprise State Roaming": false + }, + "6511755b-c27d-4c66-a59e-b835e6b54e7f": null + }, + "consumedService": { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": true, + "Access Review": false, + "Entitlement Management": false, + "Identity Protection": true + }, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { + "Conditional Access": true, + "Dynamic Group": false, + "Group Naming": true, + "On-Prem SSPR": false, + "Group Expiration": true, + "Provisioning Engine": true, + "Enterprise State Roaming": false + }, + "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null, + "c90f1a25-e6cd-4163-ac6c-ca7616c585a9": null + } + } + ], + "title": "License Report - License Data" + }, + "LicenseReport.FeatureBreakdown": { + "additionalProperties": { + "type": "boolean", + "examples": [true] + }, + "description": "List of features that are configured for the specific service plan's service configuration for the related principal.\nThe key is the name of the feature that is being described.\nThe value is the state of the feature configuration, `true` is in scope and `false` meaning not in scope.", + "examples": [ + { + "Conditional Access": true, + "Access Reviews": true, + "Dynamic Groups": false, + "On-Prem Password Rest": true, + "On-Prem Password Protection": false + } + ], + "title": "License Report - Feature Breakdown", + "type": "object" + }, + "LicenseReport": { + "description": "Completely calculated license report structure that is the result of a complete run.", + "examples": [ + { + "availableLicense": { + "e17b13ee-9749-488b-9289-d31a8fde045d": 123, + "2d995b6a-d4aa-4d8d-a03c-372ecb66509d": 456, + "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 789 + }, + "correlation": { + "auditTenantAccount": "admin-user@example.com", + "correlationId": "88da2253-758f-4135-9d37-64448c8b65c1", + "reportTenantAccount": "generic-user@example.com", + "tenantId": "0e1fe83f-a33f-4250-8546-225b8d45ae01" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "e17b13ee-9749-488b-9289-d31a8fde045d": 0 }, - "examples": { - "Valid version number": { - "summary": "Example valid version number", - "description": "An example string represents a valid semantic version number.", - "value": "1.2.3" - } + "assignedService": { + "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 0, + "c7bcba35-199c-41e5-8c8d-6d4e4aad8964": null + }, + "consumedService": { + "fe98c41a-d931-4f6f-a5bc-750ba7144a77": null, + "0474bdf1-ee76-4aff-a65c-6f82e5e1d5a6": { + "Something Here": true, + "Other Obscure feature": false + } + } + } + } + } + ], + "type": "object", + "properties": { + "availableLicense": { + "additionalProperties": { + "examples": [1234], + "type": "integer" + }, + "description": "Breakdown of the purchased licenses/service plans available in the tenant being audited for this run. Where the key is the ID of the service plan and the value is how many licenses are available/purchase for it.", + "examples": [ + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 1234, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 123 + } + ], + "title": "License Report - Available Licenses", + "type": "object" + }, + "correlation": { + "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + }, + "licenseData": { + "additionalProperties": { + "$ref": "#/components/schemas/LicenseReport.LicenseData" + } + } + }, + "required": ["availableLicense", "correlation", "licenseData"], + "title": "License Report - Complete Object" + }, + "LicenseEntitlement.Shield": { + "description": "Record that describes the purchased licenses for a specific tenant. More than one of these can be active at a single time.", + "properties": { + "correlationId": { + "description": "Used to correlate the license entitlements with other records.", + "examples": ["e097a3f5-9599-44a2-8923-fd3276c83ae1"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "enterpriseDeviceCount": { + "description": "Count of Enterprise Devices that are allowed to be managed.", + "examples": [5], + "format": "int32", + "type": "integer" + }, + "enterpriseInterfaceCount": { + "description": "Count of Enterprise Interfaces that are allowed to be managed.", + "examples": [6], + "format": "int32", + "type": "integer" + }, + "enterpriseIntermediaryCount": { + "description": "Count of Enterprise Intermediaries that are allowed to be managed.", + "examples": [7], + "format": "int32", + "type": "integer" + }, + "enterpriseUserCount": { + "description": "Count of Enterprise Users that are allowed to be managed.", + "examples": [8], + "format": "int32", + "type": "integer" + }, + "notValidAfter": { + "description": "Date that the entitlement expires at.", + "examples": ["2024-07-30T17:35:24.044Z"], + "format": "date-time", + "type": "string" + }, + "notValidBefore": { + "description": "Date that the entitlement becomes active at.", + "examples": ["2024-07-30T17:37:15.300Z"], + "format": "date-time", + "type": "string" + }, + "privilegedDeviceCount": { + "description": "Count of Privileged Devices (PAW) that are allowed to be managed.", + "examples": [9], + "format": "int32", + "type": "integer" + }, + "privilegedInterfaceCount": { + "description": "Count of Privileged Interfaces that are allowed to be managed.", + "examples": [10], + "format": "int32", + "type": "integer" + }, + "privilegedIntermediaryCount": { + "description": "Count of Privileged Intermediaries that are allowed to be managed.", + "examples": [11], + "format": "int32", + "type": "integer" + }, + "privilegedUserCount": { + "description": "Count of Privileged Users that are allowed to be managed.", + "examples": [12], + "format": "int32", + "type": "integer" + }, + "purchaseId": { + "description": "This could be any value used to correlate the purchase operation to this entitlement record.", + "examples": ["Bob's your uncle."], + "type": "string" + }, + "specializedDeviceCount": { + "description": "Count of Specialized Devices that are allowed to be managed.", + "examples": [13], + "format": "int32", + "type": "integer" + }, + "specializedInterfaceCount": { + "description": "Count of Specialized Interfaces that are allowed to be managed.", + "examples": [14], + "format": "int32", + "type": "integer" + }, + "specializedIntermediaryCount": { + "description": "Count of Specialized Intermediaries that are allowed to be managed.", + "examples": [15], + "format": "int32", + "type": "integer" + }, + "specializedUserCount": { + "description": "Count of Specialized Users that are allowed to be managed.", + "examples": [15], + "format": "int32", + "type": "integer" + }, + "tenantId": { + "description": "Tenant that this license entitlement is valid for.", + "examples": ["a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + } + }, + "required": [ + "enterpriseDeviceCount", + "enterpriseInterfaceCount", + "enterpriseIntermediaryCount", + "enterpriseUserCount", + "notValidAfter", + "notValidBefore", + "privilegedDeviceCount", + "privilegedInterfaceCount", + "privilegedIntermediaryCount", + "privilegedUserCount", + "specializedDeviceCount", + "specializedInterfaceCount", + "specializedIntermediaryCount", + "specializedUserCount", + "tenantId" + ], + "title": "License Entitlement - SHIELD Record", + "type": "object", + "examples": [ + { + "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "enterpriseDeviceCount": 5, + "enterpriseInterfaceCount": 6, + "enterpriseIntermediaryCount": 7, + "enterpriseUserCount": 8, + "notValidAfter": "2024-07-30T17:35:24.044Z", + "notValidBefore": "2024-07-30T17:37:15.300Z", + "privilegedDeviceCount": 9, + "privilegedInterfaceCount": 10, + "privilegedIntermediaryCount": 11, + "privilegedUserCount": 12, + "purchaseId": "any arbitrary string as purchaseId", + "specializedDeviceCount": 13, + "specializedInterfaceCount": 14, + "specializedIntermediaryCount": 15, + "specializedUserCount": 15, + "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" + } + ] + }, + "LicenseEntitlement.Shield.Count": { + "properties": { + "enterpriseDeviceCount": { + "description": "Count of Enterprise Devices that are allowed to be managed.", + "examples": [5], + "format": "int32", + "type": "integer" + }, + "enterpriseInterfaceCount": { + "description": "Count of Enterprise Interfaces that are allowed to be managed.", + "examples": [3], + "format": "int32", + "type": "integer" + }, + "enterpriseIntermediaryCount": { + "description": "Count of Enterprise Intermediaries that are allowed to be managed.", + "examples": [7], + "format": "int32", + "type": "integer" + }, + "enterpriseUserCount": { + "description": "Count of Enterprise Users that are allowed to be managed.", + "examples": [8], + "format": "int32", + "type": "integer" + }, + "privilegedDeviceCount": { + "description": "Count of Privileged Devices (PAW) that are allowed to be managed.", + "examples": [9], + "format": "int32", + "type": "integer" + }, + "privilegedInterfaceCount": { + "description": "Count of Privileged Interfaces that are allowed to be managed.", + "examples": [10], + "format": "int32", + "type": "integer" + }, + "privilegedIntermediaryCount": { + "description": "Count of Privileged Intermediaries that are allowed to be managed.", + "examples": [11], + "format": "int32", + "type": "integer" + }, + "privilegedUserCount": { + "description": "Count of Privileged Users that are allowed to be managed.", + "examples": [12], + "format": "int32", + "type": "integer" + }, + "specializedDeviceCount": { + "description": "Count of Specialized Devices that are allowed to be managed.", + "examples": [13], + "format": "int32", + "type": "integer" + }, + "specializedInterfaceCount": { + "description": "Count of Specialized Interfaces that are allowed to be managed.", + "examples": [14], + "format": "int32", + "type": "integer" + }, + "specializedIntermediaryCount": { + "description": "Count of Specialized Intermediaries that are allowed to be managed.", + "examples": [15], + "format": "int32", + "type": "integer" + }, + "specializedUserCount": { + "description": "Count of Specialized Users that are allowed to be managed.", + "examples": [15], + "format": "int32", + "type": "integer" + } + }, + "required": [ + "enterpriseDeviceCount", + "enterpriseInterfaceCount", + "enterpriseIntermediaryCount", + "enterpriseUserCount", + "privilegedDeviceCount", + "privilegedInterfaceCount", + "privilegedIntermediaryCount", + "privilegedUserCount", + "specializedDeviceCount", + "specializedInterfaceCount", + "specializedIntermediaryCount", + "specializedUserCount" + ], + "title": "License Entitlement - Active SHIELD Count", + "type": "object", + "examples": [ + { + "enterpriseDeviceCount": 5, + "enterpriseInterfaceCount": 3, + "enterpriseIntermediaryCount": 7, + "enterpriseUserCount": 8, + "privilegedDeviceCount": 9, + "privilegedInterfaceCount": 10, + "privilegedIntermediaryCount": 11, + "privilegedUserCount": 12, + "specializedDeviceCount": 13, + "specializedInterfaceCount": 14, + "specializedIntermediaryCount": 15, + "specializedUserCount": 15 + } + ] + }, + "Telemetry.Shield": { + "properties": { + "correlationId": { + "description": "Primary key for the table, used to correlate multiple telemetry records together.", + "format": "uuid", + "type": "string", + "examples": ["1d71e0fe-6e4a-464d-a690-80addf3bda55"] + }, + "enterpriseDeviceCount": { + "description": "Count of Enterprise Devices that are deployed in the CX environment.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "enterpriseInterfaceCount": { + "description": "Number of active Enterprise interfaces.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "enterpriseIntermediaryCount": { + "description": "Number of active Enterprise intermediaries.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "enterpriseUserCount": { + "description": "Count of Enterprise Users that are deployed in the CX environment.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "monthlyActiveEntUsers": { + "description": "Number of active managed Enterprise users.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "monthlyActivePrivUsers": { + "description": "Number of active managed privileged users.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "monthlyActiveSpecUsers": { + "description": "Number of active managed Specialized users.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "privilegedDeviceCount": { + "description": "Count of Privileged Devices (PAW) that are deployed in the CX environment.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "privilegedInterfaceCount": { + "description": "Number of active Privileged interfaces.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "privilegedIntermediaryCount": { + "description": "Number of active Privileged intermediaries.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "privilegedUserCount": { + "description": "Count of Privileged Users that are deployed in the CX environment.", + "type": "integer", + "minimum": 0, + "examples": [0] + }, + "shieldArchitectureVersion": { + "description": "Version number of the architecture that is deployed.", + "examples": ["27"], + "type": "string", + "minLength": 1 + }, + "shieldCoreVersion": { + "description": "Version number of the product that the product is running.", + "examples": ["2.5.6"], + "type": "string" + }, + "specializedDeviceCount": { + "description": "Count of Specialized Devices that are deployed in the CX environment.", + "type": "integer", + "minimum": 0 + }, + "specializedInterfaceCount": { + "description": "Number of active Specialized interfaces.", + "type": "integer", + "minimum": 0 + }, + "specializedIntermediaryCount": { + "description": "Number of active Specialized intermediaries.", + "type": "integer", + "minimum": 0 + }, + "specializedUserCount": { + "description": "Count of Specialized Users that are deployed in the CX environment.", + "type": "integer", + "minimum": 0 + }, + "tenantId": { + "description": "Tenant ID for the CX in question.", + "examples": ["5ae80362-6fe8-4ab1-9b6d-8dfa99d91657"], + "type": "string" + }, + "createdAt": { + "description": "Timestamp on when the record was created. This is auto managed by sequelize.", + "examples": ["2024-08-02T23:48:50.231Z"], + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp on when the record was last updated. This is auto managed by sequelize.", + "examples": ["2024-08-02T23:48:50.231Z"], + "format": "date-time", + "type": "string" + } + }, + "required": [ + "enterpriseDeviceCount", + "enterpriseInterfaceCount", + "enterpriseIntermediaryCount", + "enterpriseUserCount", + "monthlyActiveEntUsers", + "monthlyActivePrivUsers", + "monthlyActiveSpecUsers", + "privilegedDeviceCount", + "privilegedInterfaceCount", + "privilegedIntermediaryCount", + "privilegedUserCount", + "shieldArchitectureVersion", + "shieldCoreVersion", + "specializedDeviceCount", + "specializedInterfaceCount", + "specializedIntermediaryCount", + "specializedUserCount" + ], + "title": "Application Telemetry - SHIELD", + "type": "object", + "examples": [ + { + "correlationId": "1d71e0fe-6e4a-464d-a690-80addf3bda55", + "enterpriseDeviceCount": 0, + "enterpriseInterfaceCount": 0, + "enterpriseIntermediaryCount": 0, + "enterpriseUserCount": 0, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 0, + "privilegedInterfaceCount": 0, + "privilegedIntermediaryCount": 0, + "privilegedUserCount": 0, + "shieldArchitectureVersion": "27", + "shieldCoreVersion": "2.5.6", + "specializedDeviceCount": 3, + "specializedInterfaceCount": 2, + "specializedIntermediaryCount": 1, + "specializedUserCount": 0, + "tenantId": "5ae80362-6fe8-4ab1-9b6d-8dfa99d91657", + "createdAt": "2024-08-02T23:48:50.231Z", + "updatedAt": "2024-08-02T23:48:50.231Z" + } + ] + }, + "Update.Shield.Check": { + "description": "Object returning the value of the version of the latest application package available.", + "properties": { + "updateVersion": { + "description": "Latest found version of the application package.", + "examples": ["1.12.5"], + "type": "string" + } + }, + "required": ["updateVersion"], + "title": "Update SHIELD Check - latest application package version", + "type": "object", + "examples": [ + { + "updateVersion": "1.12.5" + } + ] + }, + "Update.Shield.Channel": { + "description": "Channel configuration for the SHIELD update service.", + "properties": { + "latest": { + "description": "Version number of the latest update available to the chanel.", + "examples": ["1.12.5"], + "type": "string" + }, + "name": { + "description": "(Unique) Name of the update channel that this configuration belongs to.", + "examples": ["stable"], + "type": "string" + }, + "previous": { + "description": "Version number of the number that is being replaced via ring deployment, available to all rings at the minimum.", + "examples": ["1.12.4"], + "type": "string" + } + }, + "required": ["latest", "name", "previous"], + "title": "SHIELD Update - Channel", + "type": "object", + "examples": [ + { + "latest": "1.12.5", + "name": "stable", + "previous": "1.12.4" + } + ] + }, + "Update.Shield.Channel.Ring": { + "description": "Object containing channel ring configuration.", + "properties": { + "latest": { + "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", + "examples": [true], + "type": "boolean" + }, + "number": { + "description": "Ring number that this configuration belongs to.", + "examples": [1], + "type": "integer", + "minimum": 0 + } + }, + "required": ["latest", "number"], + "title": "Update SHIELD Channel Ring - configuration entry", + "type": "object", + "examples": [ + { + "latest": true, + "number": 1 + } + ] + }, + "Update.Shield.Tenant": { + "description": "Object containing tenant update configuration.", + "properties": { + "alphaEnabled": { + "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", + "examples": [false], + "type": "boolean" + }, + "channel": { + "description": "Name of the deploy channel.", + "examples": ["stable"], + "type": "string" + }, + "ring": { + "description": "Ring number that the client is a member of for the current chanel.", + "examples": [1], + "type": "integer" + }, + "tenantId": { + "description": "Tenant ID that the configuration belongs to.", + "examples": ["a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + } + }, + "required": ["alphaEnabled", "channel", "ring", "tenantId"], + "title": "Update SHIELD Tenant - configuration entry", + "type": "object", + "examples": [ + { + "alphaEnabled": false, + "channel": "stable", + "ring": 1, + "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + } + ] + }, + "TenantDetails": { + "title": "Tenant Details Record", + "description": "Information about a single tenant record", + "properties": { + "tenantId": { + "description": "The object ID of the tenant record", + "examples": ["1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "tenantDisplayName": { + "description": "Human readable name for the tenant record", + "examples": ["Contoso - Prod"], + "type": "string" + }, + "parentId": { + "description": "The object ID of the tenant that is considered a parent to this record", + "examples": ["22354a3f-2e21-4bd2-8327-dc842cfa80c8"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "authorizedPrincipalList": { + "description": "List of object IDs that are allowed to access this record and related data.", + "type": "array", + "items": { + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string", + "examples": ["fd9a6a53-594d-41aa-950a-b21ff41d4688"] + }, + "examples": [ + [ + "fd9a6a53-594d-41aa-950a-b21ff41d4688", + "54fc12cd-403d-4c48-be12-86b807e958d3" + ] + ] + } + }, + "type": "object", + "required": [ + "tenantId", + "tenantDisplayName", + "parentId", + "authorizedPrincipalList" + ], + "examples": [ + { + "tenantId": "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d", + "tenantDisplayName": "Contoso - Prod", + "parentId": "22354a3f-2e21-4bd2-8327-dc842cfa80c8", + "authorizedPrincipalList": [ + "fd9a6a53-594d-41aa-950a-b21ff41d4688", + "54fc12cd-403d-4c48-be12-86b807e958d3" + ] + } + ] + }, + "ArchitectureReport": { + "description": "Container that represents the entire architecture report structure for a complete run of architectural analysis.", + "title": "Architecture Report - Complete Object", + "type": "object", + "properties": { + "tenantMetadata": { + "$ref": "#/components/schemas/ArchitectureReport.TenantMetadata" + }, + "correlation": { + "$ref": "#/components/schemas/ArchitectureReport.ArchitectureCorrelationRecord" + }, + "scheduling": { + "description": "@todo - Check with Elliot.", + "examples": ["2023-02-04T05:06:09.601Z"], + "format": "date-time", + "type": "string" + }, + "securityPosture": { + "$ref": "#/components/schemas/ArchitectureReport.SecurityPosture" + } + }, + "required": [ + "tenantMetadata", + "correlation", + "scheduling", + "securityPosture" + ], + "examples": [ + { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + }, + "scheduling": "2023-02-04T05:06:09.601Z", + "securityPosture": { + "device": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + }, + "user": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 0, + "totalMemberCount": 1, + "totalUserCount": 1 + } + } + ] + }, + "ArchitectureReport.ArchitectureCorrelationRecord": { + "title": "Architecture Report - Architecture Correlation Record", + "description": "Model/data structure that stores the records that contains the metadata for architecture report records. Used for cross record tracking and auditing.", + "type": "object", + "properties": { + "auditTenantAccount": { + "type": "string", + "description": "The user principal name used to authenticate into the tenant being audited.", + "examples": ["user@example.com"] + }, + "reportTenantAccount": { + "type": "string", + "description": "User account used to store/report the architecture report to the SHI Lab cloud service.", + "examples": ["user@example.com"] + }, + "tenantId": { + "type": "string", + "format": "uuid", + "description": "Tenant that the tool was run against.", + "examples": ["123e4567-e89b-12d3-a456-426614174000"] + }, + "correlationId": { + "type": "string", + "format": "uuid", + "description": "Unique Identifier that represents a single run of architectural analysis. This record is used to identify which architecture report records should be grouped together.", + "examples": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"] + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp on when the record was created. This is auto managed by sequelize.", + "examples": ["2023-02-04T05:06:09.601Z"] + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp on when the record was last updated. This is auto managed by sequelize.", + "examples": ["2023-02-04T05:06:09.601Z"] + } + }, + "required": [ + "auditTenantAccount", + "correlationId", + "createdAt", + "updatedAt", + "reportTenantAccount", + "tenantId" + ], + "examples": [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + } + ] + }, + "ArchitectureReport.TenantMetadata": { + "title": "Architecture Report - Tenant Metadata", + "description": "Metadata for the tenant.", + "type": "object", + "properties": { + "totalUserCount": { + "type": "integer", + "description": "Total count of users on the tenant.", + "examples": [0, 1] + }, + "totalGuestCount": { + "type": "integer", + "description": "Total count of guests on the tenant.", + "examples": [0, 1] + }, + "totalMemberCount": { + "type": "integer", + "description": "Total count of members on the tenant.", + "examples": [0, 1] + }, + "totalDeviceCount": { + "type": "integer", + "description": "Total count of devices on the tenant.", + "examples": [0, 1] + } + }, + "examples": [ + { + "totalDeviceCount": 1, + "totalGuestCount": 0, + "totalMemberCount": 1, + "totalUserCount": 1 + } + ] + }, + "ArchitectureReport.SecurityPosture": { + "title": "Architecture Report - Security Posture", + "description": "A collection of user and device principal assignments.", + "type": "object", + "properties": { + "device": { + "type": "object", + "description": "Device principal assignment data.", + "additionalProperties": false, + "patternProperties": { + "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$": { + "$ref": "#/components/schemas/ArchitectureReport.PrincipalAssignment" + } + } + }, + "user": { + "type": "object", + "description": "User principal assignment data.", + "additionalProperties": false, + "patternProperties": { + "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$": { + "$ref": "#/components/schemas/ArchitectureReport.PrincipalAssignment" + } + } + } + }, + "examples": [ + { + "device": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + }, + "user": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 } + } + } + } + ] + }, + "ArchitectureReport.PrincipalAssignment": { + "title": "Architecture Report - Principal Assignment", + "description": "Principal assignment for the security posture data.", + "type": "object", + "properties": { + "assignedService": { + "type": "object", + "description": "Service configuration assignment used to record the set of principals that are \"benefiting\" from the service, regardless of license status.", + "additionalProperties": false, + "patternProperties": { + "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$": { + "oneOf": [ + { + "$ref": "#/components/schemas/ArchitectureReport.FeatureBreakdown" + }, + { + "type": "null" + }, + { + "type": "number", + "examples": [0, 1] + } + ] + } }, - "parentId": { - "description": "The object ID of the parent value to operate against.", - "in": "query", - "name": "parentId", - "required": false, + "examples": [ + { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + ] + } + }, + "examples": [ + { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + ] + }, + "ArchitectureReport.FeatureBreakdown": { + "title": "Architecture Report - Feature Breakdown", + "description": "List of features that are configured for the specific service plan's service configuration for the related principal.", + "type": "object", + "additionalProperties": { + "type": "boolean", + "examples": [true] + }, + "examples": [ + { + "Feature X": true, + "Feature Y": false + } + ] + } + }, + "securitySchemes": { + "EntraID": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT", + "description": "The Access Token from Entra ID. Please note required scopes (permissions) in each endpoint." + } + } + }, + "externalDocs": { + "description": "Official Documentation", + "url": "https://docs.shilab.com" + }, + "info": { + "contact": { + "email": "elliot_huffman@shi.com", + "name": "SHI - Lab" + }, + "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", + "title": "SHI Data Gateway", + "version": "2.2.2" + }, + "openapi": "3.1.0", + "paths": { + "/Api/Core/Health": { + "get": { + "description": "Check the health of the various components of the data gateway and report back. Useful for automated health probing.", + "operationId": "/Api/ServiceHealth/Get", + "responses": { + "201": { + "description": "Service is operational!" + }, + "500": { + "description": "Service has a failure described with following report.", + "content": { + "application/json": { "schema": { - "examples": [ - "3b241101-e2bb-4255-8caf-4136c566a962" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "$ref": "#/components/schemas/Core.HealthReport" }, "examples": { - "Valid parent ID": { - "summary": "Example valid parent ID", - "description": "An example UUID string that represents a valid parent object ID.", - "value": "3b241101-e2bb-4255-8caf-4136c566a962" + "Auth system failure": { + "summary": "Example health report - Auth failure", + "description": "An example health report returned indicates the authentication components are not working.", + "value": { + "authClient": false, + "authServer": false, + "bulkStorage": true, + "database": true + } + }, + "Storage system failure": { + "summary": "Example health report - Storage failure", + "description": "An example health report returned indicates the storage components are not working.", + "value": { + "authClient": true, + "authServer": true, + "bulkStorage": false, + "database": false } + } } - }, - "dateStart": { - "description": "Date string to narrow records selection to those created on or after that date.", - "in": "query", - "name": "dateStart", - "required": false, - "schema": { - "examples": [ - "2025-01-01T00:00:00Z" - ], - "format": "date-time", - "type": "string" + } + } + } + }, + "tags": ["Core System"], + "security": [], + "summary": "Health of the Service for Probing" + } + }, + "/Api/LicenseReport": { + "post": { + "description": "Store the results of a license analytics run.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/LicenseReport/Post", + "requestBody": { + "content": { + "application/json": { + "examples": { + "License Report": { + "description": "Sample, truncated report from an example customer environment. The request body is the License Report that to be stored.", + "summary": "Example License Report Request", + "value": { + "availableLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, + "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, + "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, + "d76878d6-1495-4243-a334-a82bb9818cd0": 500 + }, + "correlation": { + "auditTenantAccount": "somebodyThatI@UsedToKnow.com" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, + "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { + "Something Here": true, + "Other Obscure feature": false + } + } + }, + "04e88835-771a-482b-9d6f-ba06c32cbb67": { + "assignedLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "9d3603de-b378-4c4a-adcc-ee133cbef914": null, + "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { + "Something Here": true, + "Other Obscure feature": false + } + } + } + } + } }, + "Ignorant License Report Request": { + "description": "Clueless dev trying to automate this application without reading the docs. RTFM!", + "summary": "Ignorant License Report Request", + "value": {} + } + }, + "schema": { + "$ref": "#/components/schemas/LicenseReport" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { "examples": { - "Valid start date": { - "summary": "Example valid start date", - "description": "An example ISO8601 date string that represents a valid start date in a query.", - "value": "2025-01-01T00:00:00Z" + "License Report": { + "description": "Sample, truncated report from an example customer environment. This will return the same report as the request input.", + "summary": "Example of license report stored.", + "value": { + "availableLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, + "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, + "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, + "d76878d6-1495-4243-a334-a82bb9818cd0": 500 + }, + "correlation": { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, + "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { + "Something Here": true, + "Other Obscure feature": false + } + } + }, + "04e88835-771a-482b-9d6f-ba06c32cbb67": { + "assignedLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "9d3603de-b378-4c4a-adcc-ee133cbef914": null, + "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { + "Something Here": true, + "Other Obscure feature": false + } + } + } + } } + } + }, + "schema": { + "$ref": "#/components/schemas/LicenseReport" } + } }, - "dateEnd": { - "description": "Date string to narrow records selection to those created before or on that date.", - "in": "query", - "name": "dateEnd", - "required": false, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["License Analytics"], + "summary": "Store License Analytics Data" + } + }, + "/Api/LicenseReport/Correlation": { + "get": { + "description": "Retrieves the list of correlation records for the authenticated tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific license report.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.Read.All`, `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/LicenseReport/Correlation/Get", + "parameters": [ + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Example Correlation Records": { + "description": "Sample list of correlation records for the current authenticated tenant.", + "summary": "Available Correlation Records", + "value": [ + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-08-01T21:14:45.026Z", + "updatedAt": "2024-08-01T21:14:45.026Z" + }, + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-07-25T21:14:45.026Z", + "updatedAt": "2024-07-25T21:14:45.026Z" + } + ] + } + }, "schema": { - "examples": [ - "2025-02-05T23:59:59Z" - ], - "format": "date-time", - "type": "string" + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + }, + "examples": [ + [ + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-08-01T21:14:45.026Z", + "updatedAt": "2024-08-01T21:14:45.026Z" + }, + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-07-25T21:14:45.026Z", + "updatedAt": "2024-07-25T21:14:45.026Z" + } + ] + ] + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["License Analytics"], + "summary": "Retrieve the List of Correlation Records" + } + }, + "/Api/LicenseReport/Correlation/Tenant/{tenantId}": { + "get": { + "description": "Retrieves the list of correlation records for the specified tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific license report.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/LicenseReport/Correlation/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Example Correlation Records": { + "description": "Sample list of correlation records for the specified tenant.", + "summary": "Available Correlation Records", + "value": [ + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-08-01T21:14:45.026Z", + "updatedAt": "2024-08-01T21:14:45.026Z" + }, + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-07-25T21:14:45.026Z", + "updatedAt": "2024-07-25T21:14:45.026Z" + } + ] + } }, + "schema": { + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + }, + "examples": [ + [ + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-08-01T21:14:45.026Z", + "updatedAt": "2024-08-01T21:14:45.026Z" + }, + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-07-25T21:14:45.026Z", + "updatedAt": "2024-07-25T21:14:45.026Z" + } + ] + ] + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["License Analytics"], + "summary": "Retrieve the List of Correlation Records for Specified Tenant" + } + }, + "/Api/LicenseReport/Correlation/{correlationId}/Data": { + "get": { + "description": "Retrieves the full license report for the specified correlation ID in the authenticated tenant. The license report contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.Read.All`, `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/LicenseReport/Correlation/:correlationId/Data/Get", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { "examples": { - "Valid end date": { - "summary": "Example valid end date", - "description": "An example ISO8601 date string that represents a valid end date in a query.", - "value": "2025-02-05T23:59:59Z" + "Example License Report": { + "description": "Sample, truncated license report from an example customer environment for a correlation record of the current authenticated tenant.", + "summary": "Example License Report", + "value": { + "availableLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, + "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, + "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, + "d76878d6-1495-4243-a334-a82bb9818cd0": 500 + }, + "correlation": { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, + "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { + "Something Here": true, + "Other Obscure feature": false + } + } + }, + "04e88835-771a-482b-9d6f-ba06c32cbb67": { + "assignedLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "9d3603de-b378-4c4a-adcc-ee133cbef914": null, + "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { + "Something Here": true, + "Other Obscure feature": false + } + } + } + } } + } + }, + "schema": { + "$ref": "#/components/schemas/LicenseReport" } - } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } }, + "tags": ["License Analytics"], + "summary": "Retrieve the Specified License Report" + }, + "delete": { + "description": "Deletes the full license report for the specified correlation ID.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/LicenseReport/Correlation/:correlationId/Data/delete", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + } + ], "responses": { - "400": { - "description": "Invalid input!" - }, - "401": { - "description": "Principal is not authorized to access this endpoint. Check to make sure the Bearer token is valid and present!" - }, - "403": { - "description": "Principal does not contain the correct scopes (permissions) for the API call that was made, or was made from the wrong tenant. If the permissions were granted, ensure that the access token was requested with the correct scopes." - }, - "404": { - "description": "The requested object was not found." - }, - "503": { - "description": "App is starting still. Feature is not available. Please try again later." - }, - "525": { - "description": "Infrastructure not deployed. Please deploy the infrastructure before using this endpoint." - } + "201": { + "description": "Deleted successfully" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } }, - "schemas": { - "Core.HealthReport": { - "description": "Health report that indicates if a service is down or not that the data gateway relies on.", - "properties": { - "authClient": { - "description": "Flag that indicates if the client side authentication validation is working or not.", - "examples": [ - false - ], - "type": "boolean" - }, - "authServer": { - "description": "Flag that indicates if the server side authentication is working or not.", - "examples": [ - true - ], - "type": "boolean" - }, - "bulkStorage": { - "description": "Flag that indicates if the bulk storage system is down (`false`) or not (`true`). False indicate the service is not working, true indicates the service is working.", - "examples": [ - true - ], - "type": "boolean" - }, - "database": { - "description": "Flag that indicates if the ORM (Database) system is down (`false`) or not (`true`). False indicate the service is not working, true indicates the service is working.", - "examples": [ - false - ], - "type": "boolean" + "tags": ["License Analytics"], + "summary": "Delete the Specified License Report for the currently authenticated tenant." + } + }, + "/Api/LicenseReport/Correlation/{correlationId}/Tenant/{tenantId}/Data": { + "get": { + "description": "Retrieves the full license report for the specified correlation ID and tenant. The license report contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/LicenseReport/Correlation/:correlationId/Tenant/:tenantId/Data/Get", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + }, + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "License Report": { + "description": "Sample, truncated report from an example customer environment for a correlation record of the specified tenant.", + "summary": "Example License Report", + "value": { + "availableLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, + "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, + "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, + "d76878d6-1495-4243-a334-a82bb9818cd0": 500 + }, + "correlation": { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, + "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { + "Something Here": true, + "Other Obscure feature": false + } + } + }, + "04e88835-771a-482b-9d6f-ba06c32cbb67": { + "assignedLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "9d3603de-b378-4c4a-adcc-ee133cbef914": null, + "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { + "Something Here": true, + "Other Obscure feature": false + } + } + } + } } + } }, - "required": [ - "authClient", - "authServer", - "bulkStorage", - "database" - ], - "title": "Core System - Health Report", - "type": "object", - "examples": [ - { - "authClient": false, - "authServer": true, - "bulkStorage": true, - "database": false - } - ] + "schema": { + "$ref": "#/components/schemas/LicenseReport" + } + } }, - "Chat.OpenAIChatMessage": { - "title": "Chat - Message Record", - "description": "Object representing entity supplied to the AI agent or a response from the AI Agent", - "examples": [ - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["License Analytics"], + "summary": "Retrieve the Specified License Report for Specified Tenant" + }, + "delete": { + "description": "Deletes the full license report for the specified correlation ID and tenant.\n\nThis endpoint requires the `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/LicenseReport/Correlation/:correlationId/Tenant/:tenantId/Data/delete", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + }, + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "201": { + "description": "Deleted successfully" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["License Analytics"], + "summary": "Delete the Specified License Report for Specified Tenant" + } + }, + "/Api/Chat/LicenseGpt": { + "post": { + "summary": "Inquire License Data from AI Agent", + "description": "Enables a conversation mode with AI agent to request details of the available license reports for the currently authenticated tenant.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.ReadWrite`, `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Chat/LicenseGpt/Post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Collection of conversation parts provided by user to be ingested by the agent", + "type": "array", + "items": { + "$ref": "#/components/schemas/Chat.OpenAIChatMessage" + } + }, + "examples": { + "Tool call": { + "summary": "Example tool call request", + "description": "An example request that represent a message initiated by the chat assistant to call a tool function for the currently authenticated tenant.", + "value": { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } + } + ] + } + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "examples": [ { - "name": "John Doe", - "role": "user", - "content": [ + "messageList": [ + { + "role": "user", + "content": "Hello" + }, + { + "role": "assistant", + "content": "Hello, how can I assist you today?" + }, + { + "role": "user", + "content": "Can you show me what correlation records I have?" + }, + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ { - "text": "What are the available IDs?", - "type": "text" + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } } - ], - "tool_call_id": "call_abc123", - "tool_calls": [ - { + ] + }, + { + "role": "tool", + "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", + "tool_call_id": "call_abc123" + }, + { + "role": "assistant", + "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" + } + ], + "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" + } + ], + "type": "object", + "properties": { + "messageList": { + "type": "array", + "description": "List of message objects in current conversation", + "items": { + "$ref": "#/components/schemas/Chat.OpenAIChatMessage" + }, + "examples": [ + [ + { + "role": "user", + "content": "Hello" + }, + { + "role": "assistant", + "content": "Hello, how can I assist you today?" + }, + { + "role": "user", + "content": "Can you show me what correlation records I have?" + }, + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ + { "id": "call_abc123", "type": "function", "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" } - } + } + ] + }, + { + "role": "tool", + "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", + "tool_call_id": "call_abc123" + }, + { + "role": "assistant", + "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" + } ] + ] + }, + "responseText": { + "type": "string", + "description": "Most recent response text", + "examples": [ + "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" + ] } - ], - "type": "object", - "properties": { - "content": { - "oneOf": [ - { - "type": "string", - "description": "The contents of the message" - }, + }, + "required": ["messageList", "responseText"] + }, + "examples": { + "Chat response": { + "summary": "Example chat response with context", + "description": "An example chat response that includes context of current chat session with the request appended for the currently authenticated tenant.", + "value": { + "messageList": [ + { + "role": "user", + "content": "Hello" + }, + { + "role": "assistant", + "content": "Hello, how can I assist you today?" + }, + { + "role": "user", + "content": "Can you show me what correlation records I have?" + }, + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ { - "type": "array", - "description": "The contents of the message", - "items": { - "type": "object", - "properties": { - "text": { - "type": "string", - "description": "The text content" - }, - "type": { - "type": "string", - "description": "The type of the content part" - } - }, - "required": [ - "text", - "type" - ] - }, - "examples": [ - [ - { - "text": "What are the available IDs?", - "type": "text" - } - ] - ] + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } } - ] - }, - "role": { - "type": "string", - "description": "The role of the messages author", - "examples": [ - "assistant" - ] - }, - "name": { - "type": "string", - "description": "An optional name for the participant", - "examples": [ - "John Doe" - ] - }, - "tool_calls": { - "type": "array", - "description": "The tool calls generated by the model, such as function calls", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the tool call", - "examples": [ - "call_abc121" - ] - }, - "function": { - "type": "object", - "description": "The function that the model called", - "properties": { - "arguments": { - "type": "string", - "description": "The arguments to call the function with", - "examples": [ - "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}" - ] - }, - "name": { - "type": "string", - "description": "The name of the function to call", - "examples": [ - "getCorrelationIDs" - ] - } - }, - "examples": [ - { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - ] - }, - "type": { - "type": "string", - "description": "The type of the tool. Currently, only `function` is supported", - "examples": [ - "function" - ] - } - }, - "examples": [ - { - "id": "call_abc121", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - }, - "type": "function" - } - ] + ] + }, + { + "role": "tool", + "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", + "tool_call_id": "call_abc123" + }, + { + "role": "assistant", + "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } - }, - "tool_call_id": { - "type": "string", - "description": "Tool call that this message is responding to", - "examples": [ - "call_abc123" - ] + ], + "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } - }, - "required": [ - "content", - "role" - ] + } + } + } }, - "LicenseReport.CorrelationRecord": { - "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + } + }, + "tags": ["Chat"] + } + }, + "/Api/Chat/LicenseGpt/Tenant/{tenantId}": { + "post": { + "summary": "Inquire License Data from AI Agent", + "description": "Enables a conversation mode with AI agent to request details of the available license reports for the specified tenant.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Chat/LicenseGpt/Tenant/:tenantId/Post", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Collection of conversation parts provided by user to be ingested by the agent", + "type": "array", + "items": { + "$ref": "#/components/schemas/Chat.OpenAIChatMessage" + }, "examples": [ + [ { - "auditTenantAccount": "priv-user@example.com", - "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", - "reportTenantAccount": "ent-user@example.com", - "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", - "createdAt": "2024-08-01T21:13:12.821Z", - "updatedAt": "2024-08-01T21:13:12.821Z" + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } + } + ] } - ], - "properties": { - "auditTenantAccount": { - "description": "The user account used to retrieve the license information in the tenant being audited.", - "examples": [ - "admin-user@example.com" - ], - "format": "email", - "type": "string" - }, - "correlationId": { - "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", - "examples": [ - "88da2253-758f-4135-9d37-64448c8b65c1" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "reportTenantAccount": { - "description": "User account used to store/report the license report to the SHI Lab cloud service.", - "examples": [ - "generic-user@example.com" - ], - "format": "email", - "type": "string" - }, - "tenantId": { - "description": "Unique ID of customer's Microsoft tenant that the license report is for.", - "examples": [ - "0e1fe83f-a33f-4250-8546-225b8d45ae01" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "createdAt": { - "description": "Timestamp of when the report was created.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - }, - "updatedAt": { - "description": "Timestamp of when the report was last updated.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" + ] + ] + }, + "examples": { + "Chat request": { + "summary": "Example chat request", + "description": "An example request that represent a message initiated by the chat assistant to call a tool function for the specified tenant.", + "value": [ + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } + } + ] } - }, - "required": [ - "auditTenantAccount" - ], - "title": "License Report - Correlation Record", - "type": "object" - }, - "LicenseReport.LicenseData": { - "type": "object", - "properties": { - "assignedLicense": { - "additionalProperties": { - "oneOf": [ - { - "type": "integer", - "examples": [ - 0 - ] - }, - { - "type": "null" - } - ] + ] + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "messageList": [ + { + "role": "user", + "content": "Hello" }, - "description": "License assignment on the specified principal.", - "type": "object", - "examples": [ - { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0 - } - ] - }, - "assignedService": { - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" - }, - { - "type": "integer", - "format": "int32", - "examples": [ - 0 - ] - }, - { - "type": "null" - } - ] + { + "role": "assistant", + "content": "Hello, how can I assist you today?" }, - "description": "Service configuration assignment. This is used to record the set of principals that are \"benefiting\" from the service, regardless of license status.", - "type": "object", - "examples": [ - { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, - "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null - }, - { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": { - "Conditional Access": false, - "Access Review": true, - "Entitlement Management": false, - "Identity Protection": true - } - } - ] - }, - "consumedService": { - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" - }, - { - "type": "integer", - "format": "int32", - "examples": [ - 0 - ] - }, - { - "type": "null" - } - ] + { + "role": "user", + "content": "Can you show me what correlation records I have?" }, - "description": "Usage telemetry retrieved for the service to indicate if the specific principal is consuming the service or not, regardless of license status.", - "type": "object", - "examples": [ - { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": { - "Conditional Access": true, - "Access Review": false, - "Entitlement Management": false, - "Identity Protection": true - } - }, + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, - "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } } - ] - } - }, - "required": [ - "assignedLicense", - "assignedService", - "consumedService" - ], - "description": "Collection of principals that have had their in-use licenses and assigned licenses. Where the key is the principal ID and the value is the insights.", - "examples": [ - { - "assignedLicense": { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 1, - "7159f980-6f83-4b67-bf41-e172b3ae1352": 2 + ] }, - "assignedService": { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": { - "Conditional Access": false, - "Access Review": true, - "Entitlement Management": false, - "Identity Protection": true - }, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { - "Conditional Access": true, - "Dynamic Group": false, - "Group Naming": true, - "On-Prem SSPR": false, - "Group Expiration": true, - "Provisioning Engine": true, - "Enterprise State Roaming": false - }, - "6511755b-c27d-4c66-a59e-b835e6b54e7f": null + { + "role": "tool", + "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", + "tool_call_id": "call_abc123" }, - "consumedService": { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": { - "Conditional Access": true, - "Access Review": false, - "Entitlement Management": false, - "Identity Protection": true - }, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { - "Conditional Access": true, - "Dynamic Group": false, - "Group Naming": true, - "On-Prem SSPR": false, - "Group Expiration": true, - "Provisioning Engine": true, - "Enterprise State Roaming": false - }, - "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null, - "c90f1a25-e6cd-4163-ac6c-ca7616c585a9": null + { + "role": "assistant", + "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } + ], + "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } - ], - "title": "License Report - License Data" - }, - "LicenseReport.FeatureBreakdown": { - "additionalProperties": { - "type": "boolean", - "examples": [ - true - ] - }, - "description": "List of features that are configured for the specific service plan's service configuration for the related principal.\nThe key is the name of the feature that is being described.\nThe value is the state of the feature configuration, `true` is in scope and `false` meaning not in scope.", - "examples": [ - { - "Conditional Access": true, - "Access Reviews": true, - "Dynamic Groups": false, - "On-Prem Password Rest": true, - "On-Prem Password Protection": false + ], + "type": "object", + "properties": { + "messageList": { + "type": "array", + "description": "List of message objects in current conversation", + "items": { + "$ref": "#/components/schemas/Chat.OpenAIChatMessage" + }, + "examples": [ + [ + { + "role": "user", + "content": "Hello" + }, + { + "role": "assistant", + "content": "Hello, how can I assist you today?" + }, + { + "role": "user", + "content": "Can you show me what correlation records I have?" + }, + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } + } + ] + }, + { + "role": "tool", + "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", + "tool_call_id": "call_abc123" + }, + { + "role": "assistant", + "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" + } + ] + ] + }, + "responseText": { + "type": "string", + "description": "Most recent response text", + "examples": [ + "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" + ] } - ], - "title": "License Report - Feature Breakdown", - "type": "object" - }, - "LicenseReport": { - "description": "Completely calculated license report structure that is the result of a complete run.", - "examples": [ - { - "availableLicense": { - "e17b13ee-9749-488b-9289-d31a8fde045d": 123, - "2d995b6a-d4aa-4d8d-a03c-372ecb66509d": 456, - "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 789 + }, + "required": ["messageList", "responseText"] + }, + "examples": { + "Chat response": { + "summary": "Example chat response", + "description": "An example chat response that includes context of current chat session with the request appended for the specified tenant.", + "value": { + "messageList": [ + { + "role": "user", + "content": "Hello" }, - "correlation": { - "auditTenantAccount": "admin-user@example.com", - "correlationId": "88da2253-758f-4135-9d37-64448c8b65c1", - "reportTenantAccount": "generic-user@example.com", - "tenantId": "0e1fe83f-a33f-4250-8546-225b8d45ae01" + { + "role": "assistant", + "content": "Hello, how can I assist you today?" }, - "licenseData": { - "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { - "assignedLicense": { - "e17b13ee-9749-488b-9289-d31a8fde045d": 0 - }, - "assignedService": { - "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 0, - "c7bcba35-199c-41e5-8c8d-6d4e4aad8964": null - }, - "consumedService": { - "fe98c41a-d931-4f6f-a5bc-750ba7144a77": null, - "0474bdf1-ee76-4aff-a65c-6f82e5e1d5a6": { - "Something Here": true, - "Other Obscure feature": false - } - } - } - } - } - ], - "type": "object", - "properties": { - "availableLicense": { - "additionalProperties": { - "examples": [ - 1234 - ], - "type": "integer" + { + "role": "user", + "content": "Can you show me what correlation records I have?" }, - "description": "Breakdown of the purchased licenses/service plans available in the tenant being audited for this run. Where the key is the ID of the service plan and the value is how many licenses are available/purchase for it.", - "examples": [ + { + "role": "assistant", + "content": "What are the available IDs?", + "tool_calls": [ { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": 1234, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 123 + "id": "call_abc123", + "type": "function", + "function": { + "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", + "name": "getCorrelationIDs" + } } - ], - "title": "License Report - Available Licenses", - "type": "object" - }, - "correlation": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" - }, - "licenseData": { - "additionalProperties": { - "$ref": "#/components/schemas/LicenseReport.LicenseData" + ] + }, + { + "role": "tool", + "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", + "tool_call_id": "call_abc123" + }, + { + "role": "assistant", + "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } + ], + "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } + } + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + } + }, + "tags": ["Chat"] + } + }, + "/Api/Entitlement/Shield": { + "post": { + "description": "Creates a new license entitlement (activation) for SHIELD.\n\nThis endpoint requires the `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Entitlement/Shield/Post", + "requestBody": { + "content": { + "application/json": { + "examples": { + "Specialized Purchase": { + "description": "Add-on purchase for the specified customer for some additional specialized licenses.", + "summary": "Specialized Purchase", + "value": { + "enterpriseDeviceCount": 0, + "enterpriseInterfaceCount": 0, + "enterpriseIntermediaryCount": 0, + "enterpriseUserCount": 0, + "notValidAfter": "2024-07-30T18:09:05.970Z", + "notValidBefore": "1970-01-01T00:00:00.000Z", + "privilegedDeviceCount": 0, + "privilegedInterfaceCount": 0, + "privilegedIntermediaryCount": 0, + "privilegedUserCount": 0, + "purchaseId": "ABC123", + "specializedDeviceCount": 50, + "specializedInterfaceCount": 3, + "specializedIntermediaryCount": 1, + "specializedUserCount": 50, + "tenantId": "4b00fb78-d291-4dbd-8c0a-c93ae20bffd1" + } }, - "required": [ - "availableLicense", - "correlation", - "licenseData" - ], - "title": "License Report - Complete Object" + "Initial Purchase": { + "description": "Complete suite of components purchased for the specified customer.", + "summary": "Initial Purchase", + "value": { + "enterpriseDeviceCount": 7000, + "enterpriseInterfaceCount": 500, + "enterpriseIntermediaryCount": 10, + "enterpriseUserCount": 7000, + "notValidAfter": "2024-07-30T18:12:23.049Z", + "notValidBefore": "1970-01-01T00:00:00.000Z", + "privilegedDeviceCount": 200, + "privilegedInterfaceCount": 50, + "privilegedIntermediaryCount": 3, + "privilegedUserCount": 200, + "purchaseId": "654DEF", + "specializedDeviceCount": 1000, + "specializedInterfaceCount": 11, + "specializedIntermediaryCount": 2, + "specializedUserCount": 1000, + "tenantId": "58ffb93f-5098-4630-bfc4-eeb4664208b4" + } + }, + "Ignorant Entitlement Creation Request": { + "description": "Clueless dev trying to automate this application without reading the docs. RTFM!", + "summary": "Ignorant Entitlement Creation Request", + "value": {} + } + }, + "schema": { + "$ref": "#/components/schemas/LicenseEntitlement.Shield" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Small MSP": { + "description": "Example license entitlement for a small MSP.", + "summary": "Local MSP", + "value": { + "correlationId": "60594489-6022-4ddb-8aa5-288c8d356cf2", + "enterpriseDeviceCount": 25, + "enterpriseInterfaceCount": 25, + "enterpriseIntermediaryCount": 25, + "enterpriseUserCount": 25, + "notValidAfter": "2024-07-30T17:56:00.704Z", + "notValidBefore": "1970-01-01T00:00:00.000Z", + "privilegedDeviceCount": 10, + "privilegedInterfaceCount": 10, + "privilegedIntermediaryCount": 2, + "privilegedUserCount": 10, + "purchaseId": "Bob's your mother's brother.", + "specializedDeviceCount": 5, + "specializedInterfaceCount": 5, + "specializedIntermediaryCount": 0, + "specializedUserCount": 5, + "tenantId": "1948adeb-797f-466b-962d-cc708a69d08d" + } + }, + "Enterprise": { + "description": "Example license entitlement for an enterprise sized company.", + "summary": "Enterprise", + "value": { + "correlationId": "46569e8d-eeaa-42f4-b954-05a998108eee", + "enterpriseDeviceCount": 50000, + "enterpriseInterfaceCount": 50000, + "enterpriseIntermediaryCount": 100, + "enterpriseUserCount": 50000, + "notValidAfter": "2024-07-30T17:58:54.619Z", + "notValidBefore": "1970-01-01T00:00:00.000Z", + "privilegedDeviceCount": 300, + "privilegedInterfaceCount": 100, + "privilegedIntermediaryCount": 50, + "privilegedUserCount": 300, + "purchaseId": "Bob's your mother's brother.", + "specializedDeviceCount": 1000, + "specializedInterfaceCount": 5, + "specializedIntermediaryCount": 10, + "specializedUserCount": 1000, + "tenantId": "bf78263c-6cec-44bc-9893-024dde25a486" + } + } + }, + "schema": { + "$ref": "#/components/schemas/LicenseEntitlement.Shield" + } + } }, - "LicenseEntitlement.Shield": { - "description": "Record that describes the purchased licenses for a specific tenant. More than one of these can be active at a single time.", - "properties": { - "correlationId": { - "description": "Used to correlate the license entitlements with other records.", - "examples": [ - "e097a3f5-9599-44a2-8923-fd3276c83ae1" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" - }, - "enterpriseDeviceCount": { - "description": "Count of Enterprise Devices that are allowed to be managed.", - "examples": [ - 5 - ], - "format": "int32", - "type": "integer" - }, - "enterpriseInterfaceCount": { - "description": "Count of Enterprise Interfaces that are allowed to be managed.", - "examples": [ - 6 - ], - "format": "int32", - "type": "integer" - }, - "enterpriseIntermediaryCount": { - "description": "Count of Enterprise Intermediaries that are allowed to be managed.", - "examples": [ - 7 - ], - "format": "int32", - "type": "integer" - }, - "enterpriseUserCount": { - "description": "Count of Enterprise Users that are allowed to be managed.", - "examples": [ - 8 - ], - "format": "int32", - "type": "integer" - }, - "notValidAfter": { - "description": "Date that the entitlement expires at.", - "examples": [ - "2024-07-30T17:35:24.044Z" - ], - "format": "date-time", - "type": "string" - }, - "notValidBefore": { - "description": "Date that the entitlement becomes active at.", - "examples": [ - "2024-07-30T17:37:15.300Z" - ], - "format": "date-time", - "type": "string" - }, - "privilegedDeviceCount": { - "description": "Count of Privileged Devices (PAW) that are allowed to be managed.", - "examples": [ - 9 - ], - "format": "int32", - "type": "integer" - }, - "privilegedInterfaceCount": { - "description": "Count of Privileged Interfaces that are allowed to be managed.", - "examples": [ - 10 - ], - "format": "int32", - "type": "integer" - }, - "privilegedIntermediaryCount": { - "description": "Count of Privileged Intermediaries that are allowed to be managed.", - "examples": [ - 11 - ], - "format": "int32", - "type": "integer" - }, - "privilegedUserCount": { - "description": "Count of Privileged Users that are allowed to be managed.", - "examples": [ - 12 - ], - "format": "int32", - "type": "integer" - }, - "purchaseId": { - "description": "This could be any value used to correlate the purchase operation to this entitlement record.", - "examples": [ - "Bob's your uncle." - ], - "type": "string" - }, - "specializedDeviceCount": { - "description": "Count of Specialized Devices that are allowed to be managed.", - "examples": [ - 13 - ], - "format": "int32", - "type": "integer" - }, - "specializedInterfaceCount": { - "description": "Count of Specialized Interfaces that are allowed to be managed.", - "examples": [ - 14 - ], - "format": "int32", - "type": "integer" - }, - "specializedIntermediaryCount": { - "description": "Count of Specialized Intermediaries that are allowed to be managed.", - "examples": [ - 15 - ], - "format": "int32", - "type": "integer" - }, - "specializedUserCount": { - "description": "Count of Specialized Users that are allowed to be managed.", - "examples": [ - 15 - ], - "format": "int32", - "type": "integer" - }, - "tenantId": { - "description": "Tenant that this license entitlement is valid for.", - "examples": [ - "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["License Entitlement"], + "summary": "Creates a new License Entitlement for SHIELD." + } + }, + "/Api/Entitlement/Shield/Active": { + "get": { + "description": "Retrieves the count of licenses that are available to the authenticated tenant. No scopes (permissions) required.", + "operationId": "/Api/Entitlement/Shield/Active/Get", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Small MSP": { + "description": "Example active license count for a small MSP for the currently authenticated tenant.", + "summary": "Local MSP", + "value": { + "enterpriseDeviceCount": 54, + "enterpriseInterfaceCount": 46, + "enterpriseIntermediaryCount": 2, + "enterpriseUserCount": 54, + "privilegedDeviceCount": 12, + "privilegedInterfaceCount": 52, + "privilegedIntermediaryCount": 4, + "privilegedUserCount": 12, + "specializedDeviceCount": 20, + "specializedInterfaceCount": 15, + "specializedIntermediaryCount": 0, + "specializedUserCount": 20 + } + }, + "No Licenses": { + "description": "Example license count for a company that doesn't have any licenses for the currently authenticated tenant..", + "summary": "No License", + "value": { + "enterpriseDeviceCount": 0, + "enterpriseInterfaceCount": 0, + "enterpriseIntermediaryCount": 0, + "enterpriseUserCount": 0, + "privilegedDeviceCount": 0, + "privilegedInterfaceCount": 0, + "privilegedIntermediaryCount": 0, + "privilegedUserCount": 0, + "specializedDeviceCount": 0, + "specializedInterfaceCount": 0, + "specializedIntermediaryCount": 0, + "specializedUserCount": 0 + } + }, + "Enterprise": { + "description": "Example active license count for an enterprise sized company for the currently authenticated tenant..", + "summary": "Enterprise", + "value": { + "enterpriseDeviceCount": 60000, + "enterpriseInterfaceCount": 500, + "enterpriseIntermediaryCount": 20, + "enterpriseUserCount": 60000, + "privilegedDeviceCount": 200, + "privilegedInterfaceCount": 450, + "privilegedIntermediaryCount": 15, + "privilegedUserCount": 200, + "specializedDeviceCount": 1000, + "specializedInterfaceCount": 50, + "specializedIntermediaryCount": 2, + "specializedUserCount": 1000 } + } }, - "required": [ - "enterpriseDeviceCount", - "enterpriseInterfaceCount", - "enterpriseIntermediaryCount", - "enterpriseUserCount", - "notValidAfter", - "notValidBefore", - "privilegedDeviceCount", - "privilegedInterfaceCount", - "privilegedIntermediaryCount", - "privilegedUserCount", - "specializedDeviceCount", - "specializedInterfaceCount", - "specializedIntermediaryCount", - "specializedUserCount", - "tenantId" - ], - "title": "License Entitlement - SHIELD Record", - "type": "object", - "examples": [ - { + "schema": { + "$ref": "#/components/schemas/LicenseEntitlement.Shield.Count" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + } + }, + "tags": ["License Entitlement"], + "summary": "List of Available Licenses" + } + }, + "/Api/Entitlement/Shield/Tenant/{tenantId}": { + "get": { + "description": "Retrieves the list of license entitlements that are assigned to the specified tenant.\n\nThis endpoint requires the `LicenseEntitlement.Read.All`, or `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Entitlement/Shield/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "summary": "List of Entitlement Records for Specified Tenant", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/LicenseEntitlement.Shield" + }, + "examples": [ + [ + { "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", "enterpriseDeviceCount": 5, "enterpriseInterfaceCount": 6, @@ -909,583 +2819,707 @@ "specializedIntermediaryCount": 15, "specializedUserCount": 15, "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" - } - ] - }, - "LicenseEntitlement.Shield.Count": { - "properties": { - "enterpriseDeviceCount": { - "description": "Count of Enterprise Devices that are allowed to be managed.", - "examples": [ - 5 - ], - "format": "int32", - "type": "integer" - }, - "enterpriseInterfaceCount": { - "description": "Count of Enterprise Interfaces that are allowed to be managed.", - "examples": [ - 3 - ], - "format": "int32", - "type": "integer" - }, - "enterpriseIntermediaryCount": { - "description": "Count of Enterprise Intermediaries that are allowed to be managed.", - "examples": [ - 7 - ], - "format": "int32", - "type": "integer" - }, - "enterpriseUserCount": { - "description": "Count of Enterprise Users that are allowed to be managed.", - "examples": [ - 8 - ], - "format": "int32", - "type": "integer" - }, - "privilegedDeviceCount": { - "description": "Count of Privileged Devices (PAW) that are allowed to be managed.", - "examples": [ - 9 - ], - "format": "int32", - "type": "integer" - }, - "privilegedInterfaceCount": { - "description": "Count of Privileged Interfaces that are allowed to be managed.", - "examples": [ - 10 - ], - "format": "int32", - "type": "integer" - }, - "privilegedIntermediaryCount": { - "description": "Count of Privileged Intermediaries that are allowed to be managed.", - "examples": [ - 11 - ], - "format": "int32", - "type": "integer" - }, - "privilegedUserCount": { - "description": "Count of Privileged Users that are allowed to be managed.", - "examples": [ - 12 - ], - "format": "int32", - "type": "integer" - }, - "specializedDeviceCount": { - "description": "Count of Specialized Devices that are allowed to be managed.", - "examples": [ - 13 - ], - "format": "int32", - "type": "integer" - }, - "specializedInterfaceCount": { - "description": "Count of Specialized Interfaces that are allowed to be managed.", - "examples": [ - 14 - ], - "format": "int32", - "type": "integer" - }, - "specializedIntermediaryCount": { - "description": "Count of Specialized Intermediaries that are allowed to be managed.", - "examples": [ - 15 - ], - "format": "int32", - "type": "integer" - }, - "specializedUserCount": { - "description": "Count of Specialized Users that are allowed to be managed.", - "examples": [ - 15 - ], - "format": "int32", - "type": "integer" - } + } + ] + ] }, - "required": [ - "enterpriseDeviceCount", - "enterpriseInterfaceCount", - "enterpriseIntermediaryCount", - "enterpriseUserCount", - "privilegedDeviceCount", - "privilegedInterfaceCount", - "privilegedIntermediaryCount", - "privilegedUserCount", - "specializedDeviceCount", - "specializedInterfaceCount", - "specializedIntermediaryCount", - "specializedUserCount" - ], - "title": "License Entitlement - Active SHIELD Count", - "type": "object", - "examples": [ - { + "examples": { + "Example Purchase": { + "summary": "Example entitlement purchase", + "description": "An example SHIELD entitlement for the specified tenant.", + "value": [ + { + "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", "enterpriseDeviceCount": 5, - "enterpriseInterfaceCount": 3, + "enterpriseInterfaceCount": 6, "enterpriseIntermediaryCount": 7, "enterpriseUserCount": 8, + "notValidAfter": "2024-07-30T17:35:24.044Z", + "notValidBefore": "2024-07-30T17:37:15.300Z", "privilegedDeviceCount": 9, "privilegedInterfaceCount": 10, "privilegedIntermediaryCount": 11, "privilegedUserCount": 12, + "purchaseId": "any arbitrary string as purchaseId", "specializedDeviceCount": 13, "specializedInterfaceCount": 14, "specializedIntermediaryCount": 15, - "specializedUserCount": 15 - } - ] + "specializedUserCount": 15, + "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" + } + ] + } + } + } }, - "Telemetry.Shield": { - "properties": { - "correlationId": { - "description": "Primary key for the table, used to correlate multiple telemetry records together.", - "format": "uuid", - "type": "string", - "examples": [ - "1d71e0fe-6e4a-464d-a690-80addf3bda55" - ] - }, - "enterpriseDeviceCount": { - "description": "Count of Enterprise Devices that are deployed in the CX environment.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "enterpriseInterfaceCount": { - "description": "Number of active Enterprise interfaces.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "enterpriseIntermediaryCount": { - "description": "Number of active Enterprise intermediaries.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "enterpriseUserCount": { - "description": "Count of Enterprise Users that are deployed in the CX environment.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "monthlyActiveEntUsers": { - "description": "Number of active managed Enterprise users.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "monthlyActivePrivUsers": { - "description": "Number of active managed privileged users.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "monthlyActiveSpecUsers": { - "description": "Number of active managed Specialized users.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "privilegedDeviceCount": { - "description": "Count of Privileged Devices (PAW) that are deployed in the CX environment.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "privilegedInterfaceCount": { - "description": "Number of active Privileged interfaces.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "privilegedIntermediaryCount": { - "description": "Number of active Privileged intermediaries.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "privilegedUserCount": { - "description": "Count of Privileged Users that are deployed in the CX environment.", - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "shieldArchitectureVersion": { - "description": "Version number of the architecture that is deployed.", - "examples": [ - "27" - ], - "type": "string", - "minLength": 1 - }, - "shieldCoreVersion": { - "description": "Version number of the product that the product is running.", - "examples": [ - "2.5.6" - ], - "type": "string" - }, - "specializedDeviceCount": { - "description": "Count of Specialized Devices that are deployed in the CX environment.", - "type": "integer", - "minimum": 0 - }, - "specializedInterfaceCount": { - "description": "Number of active Specialized interfaces.", - "type": "integer", - "minimum": 0 - }, - "specializedIntermediaryCount": { - "description": "Number of active Specialized intermediaries.", - "type": "integer", - "minimum": 0 - }, - "specializedUserCount": { - "description": "Count of Specialized Users that are deployed in the CX environment.", - "type": "integer", - "minimum": 0 - }, - "tenantId": { - "description": "Tenant ID for the CX in question.", - "examples": [ - "5ae80362-6fe8-4ab1-9b6d-8dfa99d91657" - ], - "type": "string" - }, - "createdAt": { - "description": "Timestamp on when the record was created. This is auto managed by sequelize.", - "examples": [ - "2024-08-02T23:48:50.231Z" - ], - "format": "date-time", - "type": "string" - }, - "updatedAt": { - "description": "Timestamp on when the record was last updated. This is auto managed by sequelize.", - "examples": [ - "2024-08-02T23:48:50.231Z" - ], - "format": "date-time", - "type": "string" + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["License Entitlement"] + } + }, + "/Api/Entitlement/Shield/Tenant/{tenantId}/Correlation/{correlationId}": { + "delete": { + "description": "Deletes the requested SHIELD license entitlement record.\n\nThis endpoint requires the `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Entitlement/Shield/Tenant/:tenantId/Correlation/:correlationId/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/correlationId" + } + ], + "summary": "Delete Specified License Entitlement", + "responses": { + "201": { + "description": "Deleted Successfully" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": ["License Entitlement"] + } + }, + "/Api/Telemetry/Shield": { + "post": { + "description": "Submits the telemetry report for SHIELD.\n\nThis endpoint requires the `Telemetry.Shield.ReadWrite`, or `Telemetry.Shield.ReadWrite.All` scope (permission).", + "operationId": "/Api/Telemetry/Shield/Post", + "requestBody": { + "content": { + "application/json": { + "examples": { + "Monthly Report": { + "description": "Example monthly telemetry report for an enterprise organization.", + "summary": "Monthly Report", + "value": { + "enterpriseDeviceCount": 64221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 642219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238 + } + } + }, + "schema": { + "$ref": "#/components/schemas/Telemetry.Shield" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Monthly Report": { + "description": "An example of latest monthly telemetry report for an enterprise organization after the latest telemetry input.", + "summary": "Updated Monthly Report", + "value": { + "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", + "enterpriseDeviceCount": 64221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 642219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-08-05T15:25:55.525Z", + "updatedAt": "2024-08-05T15:25:55.525Z" } + } }, - "required": [ - "enterpriseDeviceCount", - "enterpriseInterfaceCount", - "enterpriseIntermediaryCount", - "enterpriseUserCount", - "monthlyActiveEntUsers", - "monthlyActivePrivUsers", - "monthlyActiveSpecUsers", - "privilegedDeviceCount", - "privilegedInterfaceCount", - "privilegedIntermediaryCount", - "privilegedUserCount", - "shieldArchitectureVersion", - "shieldCoreVersion", - "specializedDeviceCount", - "specializedInterfaceCount", - "specializedIntermediaryCount", - "specializedUserCount" - ], - "title": "Application Telemetry - SHIELD", - "type": "object", - "examples": [ - { - "correlationId": "1d71e0fe-6e4a-464d-a690-80addf3bda55", - "enterpriseDeviceCount": 0, - "enterpriseInterfaceCount": 0, - "enterpriseIntermediaryCount": 0, - "enterpriseUserCount": 0, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 0, - "privilegedInterfaceCount": 0, - "privilegedIntermediaryCount": 0, - "privilegedUserCount": 0, - "shieldArchitectureVersion": "27", - "shieldCoreVersion": "2.5.6", - "specializedDeviceCount": 3, - "specializedInterfaceCount": 2, - "specializedIntermediaryCount": 1, - "specializedUserCount": 0, - "tenantId": "5ae80362-6fe8-4ab1-9b6d-8dfa99d91657", - "createdAt": "2024-08-02T23:48:50.231Z", - "updatedAt": "2024-08-02T23:48:50.231Z" - } - ] + "schema": { + "$ref": "#/components/schemas/Telemetry.Shield" + } + } }, - "Update.Shield.Check": { - "description": "Object returning the value of the version of the latest application package available.", - "properties": { - "updateVersion": { - "description": "Latest found version of the application package.", - "examples": [ - "1.12.5" - ], - "type": "string" - } + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["Telemetry"], + "summary": "Collects SHIELD Telemetry" + }, + "get": { + "description": "Retrieves the telemetry records that have been reported for the authenticated tenant. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read`, `Telemetry.Shield.Read.All`, `Telemetry.Shield.ReadWrite`, or `Telemetry.Shield.ReadWrite.All` scope (permission).", + "operationId": "/Api/Telemetry/Shield/Get", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "List of Reports": { + "description": "List of all available SHIELD telemetry reports for the current authenticated tenant.", + "summary": "List of SHIELD telemetry reports", + "value": [ + { + "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", + "enterpriseDeviceCount": 64221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 642219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-08-05T15:25:55.525Z", + "updatedAt": "2024-08-05T15:25:55.525Z" + }, + { + "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", + "enterpriseDeviceCount": 63221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 632219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-07-05T15:25:55.525Z", + "updatedAt": "2024-07-05T15:25:55.525Z" + } + ] + } }, - "required": [ - "updateVersion" - ], - "title": "Update SHIELD Check - latest application package version", - "type": "object", - "examples": [ - { - "updateVersion": "1.12.5" - } - ] + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Telemetry.Shield" + }, + "minItems": 0, + "examples": [ + [ + { + "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", + "enterpriseDeviceCount": 64221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 642219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-08-05T15:25:55.525Z", + "updatedAt": "2024-08-05T15:25:55.525Z" + }, + { + "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", + "enterpriseDeviceCount": 63221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 632219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-07-05T15:25:55.525Z", + "updatedAt": "2024-07-05T15:25:55.525Z" + } + ] + ] + } + } }, - "Update.Shield.Channel": { - "description": "Channel configuration for the SHIELD update service.", - "properties": { - "latest": { - "description": "Version number of the latest update available to the chanel.", - "examples": [ - "1.12.5" - ], - "type": "string" - }, - "name": { - "description": "(Unique) Name of the update channel that this configuration belongs to.", - "examples": [ - "stable" - ], - "type": "string" - }, - "previous": { - "description": "Version number of the number that is being replaced via ring deployment, available to all rings at the minimum.", - "examples": [ - "1.12.4" - ], - "type": "string" - } + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "summary": "Lists Reported Telemetry", + "tags": ["Telemetry"] + } + }, + "/Api/Telemetry/Shield/Tenant/{tenantId}": { + "get": { + "description": "Retrieves the telemetry records that have been reported for the specified tenant. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read.All`, or `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Telemetry/Shield/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "List of Reports": { + "description": "List of all available SHIELD telemetry reports for the specified tenant.", + "summary": "List of SHIELD telemetry reports", + "value": [ + { + "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", + "enterpriseDeviceCount": 64221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 642219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-08-05T15:25:55.525Z", + "updatedAt": "2024-08-05T15:25:55.525Z" + }, + { + "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", + "enterpriseDeviceCount": 63221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 632219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-07-05T15:25:55.525Z", + "updatedAt": "2024-07-05T15:25:55.525Z" + } + ] + } }, - "required": [ - "latest", - "name", - "previous" - ], - "title": "SHIELD Update - Channel", - "type": "object", - "examples": [ - { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Telemetry.Shield" + }, + "minItems": 0, + "examples": [ + [ + { + "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", + "enterpriseDeviceCount": 64221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 642219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-08-05T15:25:55.525Z", + "updatedAt": "2024-08-05T15:25:55.525Z" + }, + { + "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", + "enterpriseDeviceCount": 63221, + "enterpriseInterfaceCount": 523, + "enterpriseIntermediaryCount": 44, + "enterpriseUserCount": 632219, + "monthlyActiveEntUsers": 0, + "monthlyActivePrivUsers": 0, + "monthlyActiveSpecUsers": 0, + "privilegedDeviceCount": 50, + "privilegedInterfaceCount": 2000, + "privilegedIntermediaryCount": 25, + "privilegedUserCount": 50, + "shieldArchitectureVersion": "2", + "shieldCoreVersion": "3.0.0", + "specializedDeviceCount": 0, + "specializedInterfaceCount": 612, + "specializedIntermediaryCount": 2, + "specializedUserCount": 5238, + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2024-07-05T15:25:55.525Z", + "updatedAt": "2024-07-05T15:25:55.525Z" + } + ] + ] + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "summary": "Retrieves Telemetry for Specified Tenant", + "tags": ["Telemetry"] + } + }, + "/Api/Telemetry/Shield/Tenant/{tenantId}/Correlation/{correlationId}": { + "delete": { + "description": "Deletes the specified telemetry record for the specified tenant.\n\nThis endpoint requires the `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Telemetry/Shield/Tenant/:tenantId/Correlation/:correlationId/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/correlationId" + } + ], + "responses": { + "201": { + "description": "Deleted Successfully" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "summary": "Delete Specified Telemetry Record", + "tags": ["Telemetry"] + } + }, + "/Api/Update/Shield/Channel": { + "get": { + "description": "Retrieves all of the channel configurations that are present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Update.Shield.Channel" + }, + "examples": [ + [ + { "latest": "1.12.5", "name": "stable", "previous": "1.12.4" - } - ] - }, - "Update.Shield.Channel.Ring": { - "description": "Object containing channel ring configuration.", - "properties": { - "latest": { - "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", - "examples": [ - true - ], - "type": "boolean" - }, - "number": { - "description": "Ring number that this configuration belongs to.", - "examples": [ - 1 - ], - "type": "integer", - "minimum": 0 - } + } + ] + ] }, - "required": [ - "latest", - "number" - ], - "title": "Update SHIELD Channel Ring - configuration entry", - "type": "object", - "examples": [ - { - "latest": true, - "number": 1 - } - ] + "examples": { + "Channel configuration": { + "summary": "Example all channel configs", + "description": "An example showing the all channel configurations.", + "value": [ + { + "latest": "1.12.5", + "name": "stable", + "previous": "1.12.4" + }, + { + "latest": "1.12.7", + "name": "alpha", + "previous": "1.12.6" + }, + { + "latest": "1.12.6", + "name": "beta", + "previous": "1.12.5" + } + ] + } + } + } }, - "Update.Shield.Tenant": { - "description": "Object containing tenant update configuration.", - "properties": { - "alphaEnabled": { - "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", - "examples": [ - false - ], - "type": "boolean" - }, - "channel": { - "description": "Name of the deploy channel.", - "examples": [ - "stable" - ], - "type": "string" - }, - "ring": { - "description": "Ring number that the client is a member of for the current chanel.", - "examples": [ - 1 - ], - "type": "integer" - }, - "tenantId": { - "description": "Tenant ID that the configuration belongs to.", - "examples": [ - "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - } + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves All Channel Configurations", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Channel/{channelName}": { + "get": { + "description": "Retrieves configuration for the specific channel from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/:channelName/Get", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel" }, - "required": [ - "alphaEnabled", - "channel", - "ring", - "tenantId" - ], - "title": "Update SHIELD Tenant - configuration entry", - "type": "object", - "examples": [ - { - "alphaEnabled": false, - "channel": "stable", - "ring": 1, - "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + "examples": { + "Stable channel config": { + "summary": "Example stable channel config", + "description": "An example showing the stable update channel configuration.", + "value": { + "latest": "1.12.5", + "name": "stable", + "previous": "1.12.4" } - ] + }, + "Alpha channel config": { + "summary": "Example alpha channel config", + "description": "An example showing the alpha update channel configuration.", + "value": { + "latest": "1.12.7", + "name": "alpha", + "previous": "1.12.6" + } + } + } + } }, - "TenantDetails": { - "title": "Tenant Details Record", - "description": "Information about a single tenant record", + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Specific Channel Configuration", + "tags": ["SHIELD - Update"] + }, + "patch": { + "description": "Updates (or adds when missing) the specified channel configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/:channelName/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Channel Configuration Details": { + "description": "Example channel configuration object that will add/update for specified channel.", + "summary": "Channel Configuration", + "value": { + "latest": "1.12.5", + "previous": "1.12.4" + } + } + }, + "schema": { + "type": "object", "properties": { - "tenantId": { - "description": "The object ID of the tenant record", - "examples": [ - "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "tenantDisplayName": { - "description": "Human readable name for the tenant record", - "examples": [ - "Contoso - Prod" - ], - "type": "string" - }, - "parentId": { - "description": "The object ID of the tenant that is considered a parent to this record", - "examples": [ - "22354a3f-2e21-4bd2-8327-dc842cfa80c8" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "authorizedPrincipalList": { - "description": "List of object IDs that are allowed to access this record and related data.", - "type": "array", - "items": { - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string", - "examples": [ - "fd9a6a53-594d-41aa-950a-b21ff41d4688" - ] - }, - "examples": [ - [ - "fd9a6a53-594d-41aa-950a-b21ff41d4688", - "54fc12cd-403d-4c48-be12-86b807e958d3" - ] - ] - } + "latest": { + "description": "Version number of the latest update available to the chanel.", + "examples": ["1.12.5"], + "type": "string" + }, + "previous": { + "description": "Version number of the number that is being replaced via ring deployment, available to all rings at the minimum.", + "examples": ["1.12.14"], + "type": "string" + } }, - "type": "object", - "required": [ - "tenantId", - "tenantDisplayName", - "parentId", - "authorizedPrincipalList" - ], "examples": [ - { - "tenantId": "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d", - "tenantDisplayName": "Contoso - Prod", - "parentId": "22354a3f-2e21-4bd2-8327-dc842cfa80c8", - "authorizedPrincipalList": [ - "fd9a6a53-594d-41aa-950a-b21ff41d4688", - "54fc12cd-403d-4c48-be12-86b807e958d3" - ] - } + { + "latest": "1.12.5", + "previous": "1.12.4" + } ] + } } + } }, - "securitySchemes": { - "EntraID": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT", - "description": "The Access Token from Entra ID. Please note required scopes (permissions) in each endpoint." - } - } - }, - "externalDocs": { - "description": "Official Documentation", - "url": "https://docs.shilab.com" - }, - "info": { - "contact": { - "email": "elliot_huffman@shi.com", - "name": "SHI - Lab" + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Channel Configuration Details": { + "description": "Example object returned on creation or update.", + "summary": "Channel Configuration", + "value": { + "latest": "1.12.5", + "name": "stable", + "previous": "1.12.4" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Upserts Channel Configuration", + "tags": ["SHIELD - Update"] + }, + "delete": { + "description": "Deletes the specified channel configuration and associated rings.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/:channelName/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], + "responses": { + "204": { + "description": "Deleted Successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", "title": "SHI Data Gateway", @@ -1534,2990 +3568,1290 @@ } } }, - "tags": [ - "Core System" - ], - "security": [], - "summary": "Health of the Service for Probing" - } + "examples": { + "All ring config": { + "summary": "Example all ring configs", + "description": "An example showing the configurations of all rings of the specified channel.", + "value": [ + { + "latest": true, + "number": 1 + }, + { + "latest": false, + "number": 0 + } + ] + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, - "/Api/LicenseReport": { - "post": { - "description": "Store the results of a license analytics run.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", - "operationId": "/Api/LicenseReport/Post", - "requestBody": { - "content": { - "application/json": { - "examples": { - "License Report": { - "description": "Sample, truncated report from an example customer environment. The request body is the License Report that to be stored.", - "summary": "Example License Report Request", - "value": { - "availableLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, - "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, - "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, - "d76878d6-1495-4243-a334-a82bb9818cd0": 500 - }, - "correlation": { - "auditTenantAccount": "somebodyThatI@UsedToKnow.com" - }, - "licenseData": { - "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { - "assignedLicense": { - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, - "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { - "Something Here": true, - "Other Obscure feature": false - } - } - }, - "04e88835-771a-482b-9d6f-ba06c32cbb67": { - "assignedLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "9d3603de-b378-4c4a-adcc-ee133cbef914": null, - "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { - "Something Here": true, - "Other Obscure feature": false - } - } - } - } - } - }, - "Ignorant License Report Request": { - "description": "Clueless dev trying to automate this application without reading the docs. RTFM!", - "summary": "Ignorant License Report Request", - "value": {} - } - }, - "schema": { - "$ref": "#/components/schemas/LicenseReport" - } - } - } + "summary": "Retrieves All Ring Configurations", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Channel/{channelName}/Ring/{number}": { + "get": { + "description": "Retrieves configuration for the specific channel ring from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Get", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/channelRing" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel.Ring" }, - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "License Report": { - "description": "Sample, truncated report from an example customer environment. This will return the same report as the request input.", - "summary": "Example of license report stored.", - "value": { - "availableLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, - "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, - "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, - "d76878d6-1495-4243-a334-a82bb9818cd0": 500 - }, - "correlation": { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" - }, - "licenseData": { - "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { - "assignedLicense": { - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, - "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { - "Something Here": true, - "Other Obscure feature": false - } - } - }, - "04e88835-771a-482b-9d6f-ba06c32cbb67": { - "assignedLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "9d3603de-b378-4c4a-adcc-ee133cbef914": null, - "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { - "Something Here": true, - "Other Obscure feature": false - } - } - } - } - } - } - }, - "schema": { - "$ref": "#/components/schemas/LicenseReport" - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" + "examples": { + "Sample ring config": { + "summary": "Example ring configuration", + "description": "An example ring configuration for the specified channel and ring.", + "value": { + "latest": true, + "number": 1 } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Specific Channel Ring Configuration", + "tags": ["SHIELD - Update"] + }, + "patch": { + "description": "Updates (or adds when missing) channel ring configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/channelRing" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Channel Ring Configuration Details": { + "description": "Example channel ring configuration object.", + "summary": "Channel Ring Configuration", + "value": { + "latest": true + } + } + }, + "schema": { + "type": "object", + "properties": { + "latest": { + "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", + "examples": [true], + "type": "boolean" + } }, - "tags": [ - "License Analytics" - ], - "summary": "Store License Analytics Data" + "examples": [ + { + "latest": false + } + ] + } } + } }, - "/Api/LicenseReport/Correlation": { - "get": { - "description": "Retrieves the list of correlation records for the authenticated tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific license report.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.Read.All`, `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", - "operationId": "/Api/LicenseReport/Correlation/Get", - "parameters": [ - { - "$ref": "#/components/parameters/dateStart" - }, - { - "$ref": "#/components/parameters/dateEnd" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Example Correlation Records": { - "description": "Sample list of correlation records for the current authenticated tenant.", - "summary": "Available Correlation Records", - "value": [ - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-08-01T21:14:45.026Z", - "updatedAt": "2024-08-01T21:14:45.026Z" - }, - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-07-25T21:14:45.026Z", - "updatedAt": "2024-07-25T21:14:45.026Z" - } - ] - } - }, - "schema": { - "type": "array", - "minItems": 0, - "items": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" - }, - "examples": [ - [ - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-08-01T21:14:45.026Z", - "updatedAt": "2024-08-01T21:14:45.026Z" - }, - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-07-25T21:14:45.026Z", - "updatedAt": "2024-07-25T21:14:45.026Z" - } - ] - ] - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Channel Ring Configuration Details": { + "description": "Example object returned on creation or update.", + "summary": "Channel Ring Configuration", + "value": { + "latest": true, + "number": 1 } + } }, - "tags": [ - "License Analytics" - ], - "summary": "Retrieve the List of Correlation Records" + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel.Ring" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Modifies Specific Channel Ring Configuration", + "tags": ["SHIELD - Update"] + }, + "delete": { + "description": "Deletes configuration of the specific channel ring.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/channelRing" + } + ], + "responses": { + "204": { + "description": "Deleted Successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Deletes Specific Channel Ring Configuration", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Channel/{channelName}/Version/{version}": { + "post": { + "description": "Uploads new version of the update package for SHIELD in a specific channel.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Channel/:channelName/Version/:version/Post", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/version" + } + ], + "requestBody": { + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } } + } }, - "/Api/LicenseReport/Correlation/Tenant/{tenantId}": { - "get": { - "description": "Retrieves the list of correlation records for the specified tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific license report.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/LicenseReport/Correlation/Tenant/:tenantId/Get", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - }, - { - "$ref": "#/components/parameters/dateStart" - }, - { - "$ref": "#/components/parameters/dateEnd" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Example Correlation Records": { - "description": "Sample list of correlation records for the specified tenant.", - "summary": "Available Correlation Records", - "value": [ - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-08-01T21:14:45.026Z", - "updatedAt": "2024-08-01T21:14:45.026Z" - }, - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-07-25T21:14:45.026Z", - "updatedAt": "2024-07-25T21:14:45.026Z" - } - ] - } - }, - "schema": { - "type": "array", - "minItems": 0, - "items": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" - }, - "examples": [ - [ - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-08-01T21:14:45.026Z", - "updatedAt": "2024-08-01T21:14:45.026Z" - }, - { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", - "createdAt": "2024-07-25T21:14:45.026Z", - "updatedAt": "2024-07-25T21:14:45.026Z" - } - ] - ] - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } + "responses": { + "204": { + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Uploads New Application Package", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Check": { + "get": { + "description": "Retrieves the latest available version of the package for the running application. Version depends on the channel associated with the current tenant, or channel mentioned in the request, or default channel value. Applicable channel would be calculated on the server for each request.", + "operationId": "/Api/Update/Shield/Check/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Check" }, - "tags": [ - "License Analytics" - ], - "summary": "Retrieve the List of Correlation Records for Specified Tenant" - } + "examples": { + "Latest package version": { + "summary": "Example latest application version", + "description": "An example showing the latest SHIELD package available.", + "value": { + "updateVersion": "1.12.5" + } + } + } + } + }, + "description": "OK" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, - "/Api/LicenseReport/Correlation/{correlationId}/Data": { - "get": { - "description": "Retrieves the full license report for the specified correlation ID in the authenticated tenant. The license report contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.Read.All`, `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", - "operationId": "/Api/LicenseReport/Correlation/:correlationId/Data/Get", - "parameters": [ - { - "$ref": "#/components/parameters/correlationId" + "summary": "Retrieves Latest Application Version Number", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Check/Channel/{channelName}": { + "get": { + "description": "Retrieves the latest available version of the package for the running application for the specific channel.", + "operationId": "/Api/Update/Shield/Check/Channel/:channelName/Get", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Check" + }, + "examples": { + "Latest package version": { + "summary": "Example latest application version", + "description": "An example showing the latest SHIELD package available for the specified channel.", + "value": { + "updateVersion": "1.12.5" } - ], - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Example License Report": { - "description": "Sample, truncated license report from an example customer environment for a correlation record of the current authenticated tenant.", - "summary": "Example License Report", - "value": { - "availableLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, - "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, - "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, - "d76878d6-1495-4243-a334-a82bb9818cd0": 500 - }, - "correlation": { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" - }, - "licenseData": { - "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { - "assignedLicense": { - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, - "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { - "Something Here": true, - "Other Obscure feature": false - } - } - }, - "04e88835-771a-482b-9d6f-ba06c32cbb67": { - "assignedLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "9d3603de-b378-4c4a-adcc-ee133cbef914": null, - "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { - "Something Here": true, - "Other Obscure feature": false - } - } - } - } - } - } - }, - "schema": { - "$ref": "#/components/schemas/LicenseReport" - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "tags": [ - "License Analytics" - ], - "summary": "Retrieve the Specified License Report" - }, - "delete": { - "description": "Deletes the full license report for the specified correlation ID.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", - "operationId": "/Api/LicenseReport/Correlation/:correlationId/Data/delete", - "parameters": [ - { - "$ref": "#/components/parameters/correlationId" - } - ], - "responses": { - "201": { - "description": "Deleted successfully" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "tags": [ - "License Analytics" - ], - "summary": "Delete the Specified License Report for the currently authenticated tenant." - } - }, - "/Api/LicenseReport/Correlation/{correlationId}/Tenant/{tenantId}/Data": { - "get": { - "description": "Retrieves the full license report for the specified correlation ID and tenant. The license report contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/LicenseReport/Correlation/:correlationId/Tenant/:tenantId/Data/Get", - "parameters": [ - { - "$ref": "#/components/parameters/correlationId" - }, - { - "$ref": "#/components/parameters/tenantId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "License Report": { - "description": "Sample, truncated report from an example customer environment for a correlation record of the specified tenant.", - "summary": "Example License Report", - "value": { - "availableLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, - "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, - "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, - "d76878d6-1495-4243-a334-a82bb9818cd0": 500 - }, - "correlation": { - "auditTenantAccount": "somebodyThatI@example.com", - "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", - "reportTenantAccount": "usedToKnow@example.com", - "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" - }, - "licenseData": { - "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { - "assignedLicense": { - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, - "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { - "Something Here": true, - "Other Obscure feature": false - } - } - }, - "04e88835-771a-482b-9d6f-ba06c32cbb67": { - "assignedLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, - "consumedService": { - "9d3603de-b378-4c4a-adcc-ee133cbef914": null, - "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { - "Something Here": true, - "Other Obscure feature": false - } - } - } - } - } - } - }, - "schema": { - "$ref": "#/components/schemas/LicenseReport" - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "tags": [ - "License Analytics" - ], - "summary": "Retrieve the Specified License Report for Specified Tenant" - }, - "delete": { - "description": "Deletes the full license report for the specified correlation ID and tenant.\n\nThis endpoint requires the `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/LicenseReport/Correlation/:correlationId/Tenant/:tenantId/Data/delete", - "parameters": [ - { - "$ref": "#/components/parameters/correlationId" - }, - { - "$ref": "#/components/parameters/tenantId" - } - ], - "responses": { - "201": { - "description": "Deleted successfully" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "tags": [ - "License Analytics" - ], - "summary": "Delete the Specified License Report for Specified Tenant" - } - }, - "/Api/Chat/LicenseGpt": { - "post": { - "summary": "Inquire License Data from AI Agent", - "description": "Enables a conversation mode with AI agent to request details of the available license reports for the currently authenticated tenant.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.ReadWrite`, `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/Chat/LicenseGpt/Post", - "requestBody": { - "content": { - "application/json": { - "schema": { - "description": "Collection of conversation parts provided by user to be ingested by the agent", - "type": "array", - "items": { - "$ref": "#/components/schemas/Chat.OpenAIChatMessage" - } - }, - "examples": { - "Tool call": { - "summary": "Example tool call request", - "description": "An example request that represent a message initiated by the chat assistant to call a tool function for the currently authenticated tenant.", - "value": { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - } - } - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "examples": [ - { - "messageList": [ - { - "role": "user", - "content": "Hello" - }, - { - "role": "assistant", - "content": "Hello, how can I assist you today?" - }, - { - "role": "user", - "content": "Can you show me what correlation records I have?" - }, - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - }, - { - "role": "tool", - "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", - "tool_call_id": "call_abc123" - }, - { - "role": "assistant", - "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ], - "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ], - "type": "object", - "properties": { - "messageList": { - "type": "array", - "description": "List of message objects in current conversation", - "items": { - "$ref": "#/components/schemas/Chat.OpenAIChatMessage" - }, - "examples": [ - [ - { - "role": "user", - "content": "Hello" - }, - { - "role": "assistant", - "content": "Hello, how can I assist you today?" - }, - { - "role": "user", - "content": "Can you show me what correlation records I have?" - }, - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - }, - { - "role": "tool", - "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", - "tool_call_id": "call_abc123" - }, - { - "role": "assistant", - "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ] - ] - }, - "responseText": { - "type": "string", - "description": "Most recent response text", - "examples": [ - "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - ] - } - }, - "required": [ - "messageList", - "responseText" - ] - }, - "examples": { - "Chat response": { - "summary": "Example chat response with context", - "description": "An example chat response that includes context of current chat session with the request appended for the currently authenticated tenant.", - "value": { - "messageList": [ - { - "role": "user", - "content": "Hello" - }, - { - "role": "assistant", - "content": "Hello, how can I assist you today?" - }, - { - "role": "user", - "content": "Can you show me what correlation records I have?" - }, - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - }, - { - "role": "tool", - "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", - "tool_call_id": "call_abc123" - }, - { - "role": "assistant", - "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ], - "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - } - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - } - }, - "tags": [ - "Chat" - ] - } - }, - "/Api/Chat/LicenseGpt/Tenant/{tenantId}": { - "post": { - "summary": "Inquire License Data from AI Agent", - "description": "Enables a conversation mode with AI agent to request details of the available license reports for the specified tenant.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/Chat/LicenseGpt/Tenant/:tenantId/Post", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "description": "Collection of conversation parts provided by user to be ingested by the agent", - "type": "array", - "items": { - "$ref": "#/components/schemas/Chat.OpenAIChatMessage" - }, - "examples": [ - [ - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - } - ] - ] - }, - "examples": { - "Chat request": { - "summary": "Example chat request", - "description": "An example request that represent a message initiated by the chat assistant to call a tool function for the specified tenant.", - "value": [ - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - } - ] - } - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "examples": [ - { - "messageList": [ - { - "role": "user", - "content": "Hello" - }, - { - "role": "assistant", - "content": "Hello, how can I assist you today?" - }, - { - "role": "user", - "content": "Can you show me what correlation records I have?" - }, - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - }, - { - "role": "tool", - "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", - "tool_call_id": "call_abc123" - }, - { - "role": "assistant", - "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ], - "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ], - "type": "object", - "properties": { - "messageList": { - "type": "array", - "description": "List of message objects in current conversation", - "items": { - "$ref": "#/components/schemas/Chat.OpenAIChatMessage" - }, - "examples": [ - [ - { - "role": "user", - "content": "Hello" - }, - { - "role": "assistant", - "content": "Hello, how can I assist you today?" - }, - { - "role": "user", - "content": "Can you show me what correlation records I have?" - }, - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - }, - { - "role": "tool", - "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", - "tool_call_id": "call_abc123" - }, - { - "role": "assistant", - "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ] - ] - }, - "responseText": { - "type": "string", - "description": "Most recent response text", - "examples": [ - "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - ] - } - }, - "required": [ - "messageList", - "responseText" - ] - }, - "examples": { - "Chat response": { - "summary": "Example chat response", - "description": "An example chat response that includes context of current chat session with the request appended for the specified tenant.", - "value": { - "messageList": [ - { - "role": "user", - "content": "Hello" - }, - { - "role": "assistant", - "content": "Hello, how can I assist you today?" - }, - { - "role": "user", - "content": "Can you show me what correlation records I have?" - }, - { - "role": "assistant", - "content": "What are the available IDs?", - "tool_calls": [ - { - "id": "call_abc123", - "type": "function", - "function": { - "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", - "name": "getCorrelationIDs" - } - } - ] - }, - { - "role": "tool", - "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", - "tool_call_id": "call_abc123" - }, - { - "role": "assistant", - "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - ], - "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" - } - } - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - } - }, - "tags": [ - "Chat" - ] - } - }, - "/Api/Entitlement/Shield": { - "post": { - "description": "Creates a new license entitlement (activation) for SHIELD.\n\nThis endpoint requires the `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/Entitlement/Shield/Post", - "requestBody": { - "content": { - "application/json": { - "examples": { - "Specialized Purchase": { - "description": "Add-on purchase for the specified customer for some additional specialized licenses.", - "summary": "Specialized Purchase", - "value": { - "enterpriseDeviceCount": 0, - "enterpriseInterfaceCount": 0, - "enterpriseIntermediaryCount": 0, - "enterpriseUserCount": 0, - "notValidAfter": "2024-07-30T18:09:05.970Z", - "notValidBefore": "1970-01-01T00:00:00.000Z", - "privilegedDeviceCount": 0, - "privilegedInterfaceCount": 0, - "privilegedIntermediaryCount": 0, - "privilegedUserCount": 0, - "purchaseId": "ABC123", - "specializedDeviceCount": 50, - "specializedInterfaceCount": 3, - "specializedIntermediaryCount": 1, - "specializedUserCount": 50, - "tenantId": "4b00fb78-d291-4dbd-8c0a-c93ae20bffd1" - } - }, - "Initial Purchase": { - "description": "Complete suite of components purchased for the specified customer.", - "summary": "Initial Purchase", - "value": { - "enterpriseDeviceCount": 7000, - "enterpriseInterfaceCount": 500, - "enterpriseIntermediaryCount": 10, - "enterpriseUserCount": 7000, - "notValidAfter": "2024-07-30T18:12:23.049Z", - "notValidBefore": "1970-01-01T00:00:00.000Z", - "privilegedDeviceCount": 200, - "privilegedInterfaceCount": 50, - "privilegedIntermediaryCount": 3, - "privilegedUserCount": 200, - "purchaseId": "654DEF", - "specializedDeviceCount": 1000, - "specializedInterfaceCount": 11, - "specializedIntermediaryCount": 2, - "specializedUserCount": 1000, - "tenantId": "58ffb93f-5098-4630-bfc4-eeb4664208b4" - } - }, - "Ignorant Entitlement Creation Request": { - "description": "Clueless dev trying to automate this application without reading the docs. RTFM!", - "summary": "Ignorant Entitlement Creation Request", - "value": {} - } - }, - "schema": { - "$ref": "#/components/schemas/LicenseEntitlement.Shield" - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Small MSP": { - "description": "Example license entitlement for a small MSP.", - "summary": "Local MSP", - "value": { - "correlationId": "60594489-6022-4ddb-8aa5-288c8d356cf2", - "enterpriseDeviceCount": 25, - "enterpriseInterfaceCount": 25, - "enterpriseIntermediaryCount": 25, - "enterpriseUserCount": 25, - "notValidAfter": "2024-07-30T17:56:00.704Z", - "notValidBefore": "1970-01-01T00:00:00.000Z", - "privilegedDeviceCount": 10, - "privilegedInterfaceCount": 10, - "privilegedIntermediaryCount": 2, - "privilegedUserCount": 10, - "purchaseId": "Bob's your mother's brother.", - "specializedDeviceCount": 5, - "specializedInterfaceCount": 5, - "specializedIntermediaryCount": 0, - "specializedUserCount": 5, - "tenantId": "1948adeb-797f-466b-962d-cc708a69d08d" - } - }, - "Enterprise": { - "description": "Example license entitlement for an enterprise sized company.", - "summary": "Enterprise", - "value": { - "correlationId": "46569e8d-eeaa-42f4-b954-05a998108eee", - "enterpriseDeviceCount": 50000, - "enterpriseInterfaceCount": 50000, - "enterpriseIntermediaryCount": 100, - "enterpriseUserCount": 50000, - "notValidAfter": "2024-07-30T17:58:54.619Z", - "notValidBefore": "1970-01-01T00:00:00.000Z", - "privilegedDeviceCount": 300, - "privilegedInterfaceCount": 100, - "privilegedIntermediaryCount": 50, - "privilegedUserCount": 300, - "purchaseId": "Bob's your mother's brother.", - "specializedDeviceCount": 1000, - "specializedInterfaceCount": 5, - "specializedIntermediaryCount": 10, - "specializedUserCount": 1000, - "tenantId": "bf78263c-6cec-44bc-9893-024dde25a486" - } - } - }, - "schema": { - "$ref": "#/components/schemas/LicenseEntitlement.Shield" - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "tags": [ - "License Entitlement" - ], - "summary": "Creates a new License Entitlement for SHIELD." - } - }, - "/Api/Entitlement/Shield/Active": { - "get": { - "description": "Retrieves the count of licenses that are available to the authenticated tenant. No scopes (permissions) required.", - "operationId": "/Api/Entitlement/Shield/Active/Get", - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Small MSP": { - "description": "Example active license count for a small MSP for the currently authenticated tenant.", - "summary": "Local MSP", - "value": { - "enterpriseDeviceCount": 54, - "enterpriseInterfaceCount": 46, - "enterpriseIntermediaryCount": 2, - "enterpriseUserCount": 54, - "privilegedDeviceCount": 12, - "privilegedInterfaceCount": 52, - "privilegedIntermediaryCount": 4, - "privilegedUserCount": 12, - "specializedDeviceCount": 20, - "specializedInterfaceCount": 15, - "specializedIntermediaryCount": 0, - "specializedUserCount": 20 - } - }, - "No Licenses": { - "description": "Example license count for a company that doesn't have any licenses for the currently authenticated tenant..", - "summary": "No License", - "value": { - "enterpriseDeviceCount": 0, - "enterpriseInterfaceCount": 0, - "enterpriseIntermediaryCount": 0, - "enterpriseUserCount": 0, - "privilegedDeviceCount": 0, - "privilegedInterfaceCount": 0, - "privilegedIntermediaryCount": 0, - "privilegedUserCount": 0, - "specializedDeviceCount": 0, - "specializedInterfaceCount": 0, - "specializedIntermediaryCount": 0, - "specializedUserCount": 0 - } - }, - "Enterprise": { - "description": "Example active license count for an enterprise sized company for the currently authenticated tenant..", - "summary": "Enterprise", - "value": { - "enterpriseDeviceCount": 60000, - "enterpriseInterfaceCount": 500, - "enterpriseIntermediaryCount": 20, - "enterpriseUserCount": 60000, - "privilegedDeviceCount": 200, - "privilegedInterfaceCount": 450, - "privilegedIntermediaryCount": 15, - "privilegedUserCount": 200, - "specializedDeviceCount": 1000, - "specializedInterfaceCount": 50, - "specializedIntermediaryCount": 2, - "specializedUserCount": 1000 - } - } - }, - "schema": { - "$ref": "#/components/schemas/LicenseEntitlement.Shield.Count" - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - } - }, - "tags": [ - "License Entitlement" - ], - "summary": "List of Available Licenses" - } - }, - "/Api/Entitlement/Shield/Tenant/{tenantId}": { - "get": { - "description": "Retrieves the list of license entitlements that are assigned to the specified tenant.\n\nThis endpoint requires the `LicenseEntitlement.Read.All`, or `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/Entitlement/Shield/Tenant/:tenantId/Get", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - } - ], - "summary": "List of Entitlement Records for Specified Tenant", - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "array", - "minItems": 0, - "items": { - "$ref": "#/components/schemas/LicenseEntitlement.Shield" - }, - "examples": [ - [ - { - "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "enterpriseDeviceCount": 5, - "enterpriseInterfaceCount": 6, - "enterpriseIntermediaryCount": 7, - "enterpriseUserCount": 8, - "notValidAfter": "2024-07-30T17:35:24.044Z", - "notValidBefore": "2024-07-30T17:37:15.300Z", - "privilegedDeviceCount": 9, - "privilegedInterfaceCount": 10, - "privilegedIntermediaryCount": 11, - "privilegedUserCount": 12, - "purchaseId": "any arbitrary string as purchaseId", - "specializedDeviceCount": 13, - "specializedInterfaceCount": 14, - "specializedIntermediaryCount": 15, - "specializedUserCount": 15, - "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" - } - ] - ] - }, - "examples": { - "Example Purchase": { - "summary": "Example entitlement purchase", - "description": "An example SHIELD entitlement for the specified tenant.", - "value": [ - { - "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "enterpriseDeviceCount": 5, - "enterpriseInterfaceCount": 6, - "enterpriseIntermediaryCount": 7, - "enterpriseUserCount": 8, - "notValidAfter": "2024-07-30T17:35:24.044Z", - "notValidBefore": "2024-07-30T17:37:15.300Z", - "privilegedDeviceCount": 9, - "privilegedInterfaceCount": 10, - "privilegedIntermediaryCount": 11, - "privilegedUserCount": 12, - "purchaseId": "any arbitrary string as purchaseId", - "specializedDeviceCount": 13, - "specializedInterfaceCount": 14, - "specializedIntermediaryCount": 15, - "specializedUserCount": 15, - "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" - } - ] - } - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "tags": [ - "License Entitlement" - ] - } - }, - "/Api/Entitlement/Shield/Tenant/{tenantId}/Correlation/{correlationId}": { - "delete": { - "description": "Deletes the requested SHIELD license entitlement record.\n\nThis endpoint requires the `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/Entitlement/Shield/Tenant/:tenantId/Correlation/:correlationId/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - }, - { - "$ref": "#/components/parameters/correlationId" - } - ], - "summary": "Delete Specified License Entitlement", - "responses": { - "201": { - "description": "Deleted Successfully" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" - } - }, - "tags": [ - "License Entitlement" - ] - } - }, - "/Api/Telemetry/Shield": { - "post": { - "description": "Submits the telemetry report for SHIELD.\n\nThis endpoint requires the `Telemetry.Shield.ReadWrite`, or `Telemetry.Shield.ReadWrite.All` scope (permission).", - "operationId": "/Api/Telemetry/Shield/Post", - "requestBody": { - "content": { - "application/json": { - "examples": { - "Monthly Report": { - "description": "Example monthly telemetry report for an enterprise organization.", - "summary": "Monthly Report", - "value": { - "enterpriseDeviceCount": 64221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 642219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238 - } - } - }, - "schema": { - "$ref": "#/components/schemas/Telemetry.Shield" - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Monthly Report": { - "description": "An example of latest monthly telemetry report for an enterprise organization after the latest telemetry input.", - "summary": "Updated Monthly Report", - "value": { - "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", - "enterpriseDeviceCount": 64221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 642219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-08-05T15:25:55.525Z", - "updatedAt": "2024-08-05T15:25:55.525Z" - } - } - }, - "schema": { - "$ref": "#/components/schemas/Telemetry.Shield" - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "tags": [ - "Telemetry" - ], - "summary": "Collects SHIELD Telemetry" - }, - "get": { - "description": "Retrieves the telemetry records that have been reported for the authenticated tenant. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read`, `Telemetry.Shield.Read.All`, `Telemetry.Shield.ReadWrite`, or `Telemetry.Shield.ReadWrite.All` scope (permission).", - "operationId": "/Api/Telemetry/Shield/Get", - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "List of Reports": { - "description": "List of all available SHIELD telemetry reports for the current authenticated tenant.", - "summary": "List of SHIELD telemetry reports", - "value": [ - { - "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", - "enterpriseDeviceCount": 64221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 642219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-08-05T15:25:55.525Z", - "updatedAt": "2024-08-05T15:25:55.525Z" - }, - { - "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", - "enterpriseDeviceCount": 63221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 632219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-07-05T15:25:55.525Z", - "updatedAt": "2024-07-05T15:25:55.525Z" - } - ] - } - }, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Telemetry.Shield" - }, - "minItems": 0, - "examples": [ - [ - { - "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", - "enterpriseDeviceCount": 64221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 642219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-08-05T15:25:55.525Z", - "updatedAt": "2024-08-05T15:25:55.525Z" - }, - { - "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", - "enterpriseDeviceCount": 63221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 632219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-07-05T15:25:55.525Z", - "updatedAt": "2024-07-05T15:25:55.525Z" - } - ] - ] - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - } - }, - "summary": "Lists Reported Telemetry", - "tags": [ - "Telemetry" - ] - } - }, - "/Api/Telemetry/Shield/Tenant/{tenantId}": { - "get": { - "description": "Retrieves the telemetry records that have been reported for the specified tenant. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read.All`, or `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/Telemetry/Shield/Tenant/:tenantId/Get", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "List of Reports": { - "description": "List of all available SHIELD telemetry reports for the specified tenant.", - "summary": "List of SHIELD telemetry reports", - "value": [ - { - "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", - "enterpriseDeviceCount": 64221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 642219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-08-05T15:25:55.525Z", - "updatedAt": "2024-08-05T15:25:55.525Z" - }, - { - "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", - "enterpriseDeviceCount": 63221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 632219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-07-05T15:25:55.525Z", - "updatedAt": "2024-07-05T15:25:55.525Z" - } - ] - } - }, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Telemetry.Shield" - }, - "minItems": 0, - "examples": [ - [ - { - "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", - "enterpriseDeviceCount": 64221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 642219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-08-05T15:25:55.525Z", - "updatedAt": "2024-08-05T15:25:55.525Z" - }, - { - "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", - "enterpriseDeviceCount": 63221, - "enterpriseInterfaceCount": 523, - "enterpriseIntermediaryCount": 44, - "enterpriseUserCount": 632219, - "monthlyActiveEntUsers": 0, - "monthlyActivePrivUsers": 0, - "monthlyActiveSpecUsers": 0, - "privilegedDeviceCount": 50, - "privilegedInterfaceCount": 2000, - "privilegedIntermediaryCount": 25, - "privilegedUserCount": 50, - "shieldArchitectureVersion": "2", - "shieldCoreVersion": "3.0.0", - "specializedDeviceCount": 0, - "specializedInterfaceCount": 612, - "specializedIntermediaryCount": 2, - "specializedUserCount": 5238, - "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", - "createdAt": "2024-07-05T15:25:55.525Z", - "updatedAt": "2024-07-05T15:25:55.525Z" - } - ] - ] - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" - } - }, - "summary": "Retrieves Telemetry for Specified Tenant", - "tags": [ - "Telemetry" - ] - } - }, - "/Api/Telemetry/Shield/Tenant/{tenantId}/Correlation/{correlationId}": { - "delete": { - "description": "Deletes the specified telemetry record for the specified tenant.\n\nThis endpoint requires the `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/Telemetry/Shield/Tenant/:tenantId/Correlation/:correlationId/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - }, - { - "$ref": "#/components/parameters/correlationId" - } - ], - "responses": { - "201": { - "description": "Deleted Successfully" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" - } - }, - "summary": "Delete Specified Telemetry Record", - "tags": [ - "Telemetry" - ] - } - }, - "/Api/Update/Shield/Channel": { - "get": { - "description": "Retrieves all of the channel configurations that are present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/Get", - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Update.Shield.Channel" - }, - "examples": [ - [ - { - "latest": "1.12.5", - "name": "stable", - "previous": "1.12.4" - } - ] - ] - }, - "examples": { - "Channel configuration": { - "summary": "Example all channel configs", - "description": "An example showing the all channel configurations.", - "value": [ - { - "latest": "1.12.5", - "name": "stable", - "previous": "1.12.4" - }, - { - "latest": "1.12.7", - "name": "alpha", - "previous": "1.12.6" - }, - { - "latest": "1.12.6", - "name": "beta", - "previous": "1.12.5" - } - ] - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Retrieves All Channel Configurations", - "tags": [ - "SHIELD - Update" - ] - } - }, - "/Api/Update/Shield/Channel/{channelName}": { - "get": { - "description": "Retrieves configuration for the specific channel from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Get", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Update.Shield.Channel" - }, - "examples": { - "Stable channel config": { - "summary": "Example stable channel config", - "description": "An example showing the stable update channel configuration.", - "value": { - "latest": "1.12.5", - "name": "stable", - "previous": "1.12.4" - } - }, - "Alpha channel config": { - "summary": "Example alpha channel config", - "description": "An example showing the alpha update channel configuration.", - "value": { - "latest": "1.12.7", - "name": "alpha", - "previous": "1.12.6" - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Retrieves Specific Channel Configuration", - "tags": [ - "SHIELD - Update" - ] - }, - "patch": { - "description": "Updates (or adds when missing) the specified channel configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Patch", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - } - ], - "requestBody": { - "content": { - "application/json": { - "examples": { - "Channel Configuration Details": { - "description": "Example channel configuration object that will add/update for specified channel.", - "summary": "Channel Configuration", - "value": { - "latest": "1.12.5", - "previous": "1.12.4" - } - } - }, - "schema": { - "type": "object", - "properties": { - "latest": { - "description": "Version number of the latest update available to the chanel.", - "examples": [ - "1.12.5" - ], - "type": "string" - }, - "previous": { - "description": "Version number of the number that is being replaced via ring deployment, available to all rings at the minimum.", - "examples": [ - "1.12.14" - ], - "type": "string" - } - }, - "examples": [ - { - "latest": "1.12.5", - "previous": "1.12.4" - } - ] - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Channel Configuration Details": { - "description": "Example object returned on creation or update.", - "summary": "Channel Configuration", - "value": { - "latest": "1.12.5", - "name": "stable", - "previous": "1.12.4" - } - } - }, - "schema": { - "$ref": "#/components/schemas/Update.Shield.Channel" - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Upserts Channel Configuration", - "tags": [ - "SHIELD - Update" - ] - }, - "delete": { - "description": "Deletes the specified channel configuration and associated rings.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - } - ], - "responses": { - "204": { - "description": "Deleted Successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Deletes the Specified Channel", - "tags": [ - "SHIELD - Update" - ] - } - }, - "/Api/Update/Shield/Channel/{channelName}/Ring": { - "get": { - "description": "Retrieves all of the ring configurations for a channel that are present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/Get", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Update.Shield.Channel.Ring" - }, - "examples": [ - [ - { - "latest": true, - "number": 1 - } - ] - ] - }, - "examples": { - "All ring config": { - "summary": "Example all ring configs", - "description": "An example showing the configurations of all rings of the specified channel.", - "value": [ - { - "latest": true, - "number": 1 - }, - { - "latest": false, - "number": 0 - } - ] - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Retrieves All Ring Configurations", - "tags": [ - "SHIELD - Update" - ] - } - }, - "/Api/Update/Shield/Channel/{channelName}/Ring/{number}": { - "get": { - "description": "Retrieves configuration for the specific channel ring from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Get", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - }, - { - "$ref": "#/components/parameters/channelRing" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Update.Shield.Channel.Ring" - }, - "examples": { - "Sample ring config": { - "summary": "Example ring configuration", - "description": "An example ring configuration for the specified channel and ring.", - "value": { - "latest": true, - "number": 1 - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Retrieves Specific Channel Ring Configuration", - "tags": [ - "SHIELD - Update" - ] - }, - "patch": { - "description": "Updates (or adds when missing) channel ring configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Patch", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - }, - { - "$ref": "#/components/parameters/channelRing" - } - ], - "requestBody": { - "content": { - "application/json": { - "examples": { - "Channel Ring Configuration Details": { - "description": "Example channel ring configuration object.", - "summary": "Channel Ring Configuration", - "value": { - "latest": true - } - } - }, - "schema": { - "type": "object", - "properties": { - "latest": { - "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", - "examples": [ - true - ], - "type": "boolean" - } - }, - "examples": [ - { - "latest": false - } - ] - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Channel Ring Configuration Details": { - "description": "Example object returned on creation or update.", - "summary": "Channel Ring Configuration", - "value": { - "latest": true, - "number": 1 - } - } - }, - "schema": { - "$ref": "#/components/schemas/Update.Shield.Channel.Ring" - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Modifies Specific Channel Ring Configuration", - "tags": [ - "SHIELD - Update" - ] + } + } + } }, - "delete": { - "description": "Deletes configuration of the specific channel ring.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - }, - { - "$ref": "#/components/parameters/channelRing" - } - ], - "responses": { - "204": { - "description": "Deleted Successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Deletes Specific Channel Ring Configuration", - "tags": [ - "SHIELD - Update" - ] - } - }, - "/Api/Update/Shield/Channel/{channelName}/Version/{version}": { - "post": { - "description": "Uploads new version of the update package for SHIELD in a specific channel.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Channel/:channelName/Version/:version/Post", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - }, - { - "$ref": "#/components/parameters/version" - } - ], - "requestBody": { - "content": { - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - } - }, - "responses": { - "204": { - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Uploads New Application Package", - "tags": [ - "SHIELD - Update" - ] - } - }, - "/Api/Update/Shield/Check": { - "get": { - "description": "Retrieves the latest available version of the package for the running application. Version depends on the channel associated with the current tenant, or channel mentioned in the request, or default channel value. Applicable channel would be calculated on the server for each request.", - "operationId": "/Api/Update/Shield/Check/Get", - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Update.Shield.Check" - }, - "examples": { - "Latest package version": { - "summary": "Example latest application version", - "description": "An example showing the latest SHIELD package available.", - "value": { - "updateVersion": "1.12.5" - } - } - } - } - }, - "description": "OK" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Retrieves Latest Application Version Number", - "tags": [ - "SHIELD - Update" - ] - } - }, - "/Api/Update/Shield/Check/Channel/{channelName}": { - "get": { - "description": "Retrieves the latest available version of the package for the running application for the specific channel.", - "operationId": "/Api/Update/Shield/Check/Channel/:channelName/Get", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Update.Shield.Check" - }, - "examples": { - "Latest package version": { - "summary": "Example latest application version", - "description": "An example showing the latest SHIELD package available for the specified channel.", - "value": { - "updateVersion": "1.12.5" - } - } - } - } - }, - "description": "OK" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Retrieves Application Version Number For Specific Channel", - "tags": [ - "SHIELD - Update" - ] - } + "description": "OK" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, - "/Api/Update/Shield/Download": { - "get": { - "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package.", - "operationId": "/Api/Update/Shield/Download/Get", - "responses": { - "200": { - "description": "OK", - "content": { - "application/zip": { - "schema": { - "type": "string", - "format": "binary", - "examples": [ - "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" - ] - }, - "examples": { - "base64-inline": { - "summary": "Base64-encoded ZIP)", - "description": "Base64 encoding of a small ZIP (truncated) to simulate a update package binary string for the channel specified.", - "value": "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" - } - } - } - } - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } + "summary": "Retrieves Application Version Number For Specific Channel", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Download": { + "get": { + "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package.", + "operationId": "/Api/Update/Shield/Download/Get", + "responses": { + "200": { + "description": "OK", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary", + "examples": [ + "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" + ] }, - "summary": "Streams File Content To Download", - "tags": [ - "SHIELD - Update" - ] + "examples": { + "base64-inline": { + "summary": "Base64-encoded ZIP)", + "description": "Base64 encoding of a small ZIP (truncated) to simulate a update package binary string for the channel specified.", + "value": "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" + } + } + } } + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, - "/Api/Update/Shield/Download/Channel/{channelName}": { - "get": { - "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package for the specific channel.", - "operationId": "/Api/Update/Shield/Download/Channel/:channelName/Get", - "parameters": [ - { - "$ref": "#/components/parameters/channelName" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/zip": { - "schema": { - "type": "string", - "format": "binary", - "examples": [ - "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" - ] - }, - "examples": { - "base64-inline": { - "summary": "Base64-encoded ZIP", - "description": "Base64 encoding of a small ZIP (truncated) to simulate a update package binary string for the channel specified.", - "value": "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" - } - } - } - } - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } + "summary": "Streams File Content To Download", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Download/Channel/{channelName}": { + "get": { + "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package for the specific channel.", + "operationId": "/Api/Update/Shield/Download/Channel/:channelName/Get", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary", + "examples": [ + "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" + ] }, - "summary": "Streams File Content From Specific Channel To Download", - "tags": [ - "SHIELD - Update" - ] + "examples": { + "base64-inline": { + "summary": "Base64-encoded ZIP", + "description": "Base64 encoding of a small ZIP (truncated) to simulate a update package binary string for the channel specified.", + "value": "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" + } + } + } } + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, - "/Api/Update/Shield/Tenant": { - "get": { - "description": "Retrieves all tenant configurations present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Tenant/Get", - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Update.Shield.Tenant" - }, - "examples": [ - [ - { - "alphaEnabled": false, - "channel": "stable", - "ring": 1, - "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" - } - ] - ] - }, - "examples": { - "All tenant list": { - "summary": "Example all tenant list", - "description": "A example truncated list of all tenant configurations that present in the update service.", - "value": [ - { - "alphaEnabled": false, - "channel": "stable", - "ring": 1, - "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" - } - ] - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } + "summary": "Streams File Content From Specific Channel To Download", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Tenant": { + "get": { + "description": "Retrieves all tenant configurations present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Tenant/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Update.Shield.Tenant" + }, + "examples": [ + [ + { + "alphaEnabled": false, + "channel": "stable", + "ring": 1, + "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + } + ] + ] }, - "summary": "Retrieves All Tenant Configurations", - "tags": [ - "SHIELD - Update" - ] - } - }, - "/Api/Update/Shield/Tenant/{tenantId}": { - "get": { - "description": "Retrieves configuration for the specific tenant from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Tenant/:tenantId/Get", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Update.Shield.Tenant" - }, - "examples": { - "Tenant config": { - "summary": "Example tenant config", - "description": "A example configurations that present in the update service of the specified tenant.", - "value": { - "alphaEnabled": false, - "channel": "stable", - "ring": 1, - "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + "examples": { + "All tenant list": { + "summary": "Example all tenant list", + "description": "A example truncated list of all tenant configurations that present in the update service.", + "value": [ + { + "alphaEnabled": false, + "channel": "stable", + "ring": 1, + "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" + } + ] + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves All Tenant Configurations", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Update/Shield/Tenant/{tenantId}": { + "get": { + "description": "Retrieves configuration for the specific tenant from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Tenant" + }, + "examples": { + "Tenant config": { + "summary": "Example tenant config", + "description": "A example configurations that present in the update service of the specified tenant.", + "value": { + "alphaEnabled": false, + "channel": "stable", + "ring": 1, + "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Specific Tenant Configuration", + "tags": ["SHIELD - Update"] + }, + "patch": { + "description": "Updates (or adds when missing) tenant configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Tenant/:tenantId/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Tenant Configuration Details": { + "description": "Example tenant configuration object.", + "summary": "Tenant Configuration", + "value": { + "alphaEnabled": false, + "channel": "stable", + "ring": 1 + } + } + }, + "schema": { + "type": "object", + "properties": { + "alphaEnabled": { + "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", + "examples": [false], + "type": "boolean" + }, + "channel": { + "description": "Name of the deploy channel.", + "examples": ["stable"], + "type": "string" + }, + "ring": { + "description": "Ring number that the client is a member of for the current chanel.", + "examples": [1], + "type": "integer" + } }, - "summary": "Retrieves Specific Tenant Configuration", - "tags": [ - "SHIELD - Update" + "examples": [ + { + "alphaEnabled": false, + "channel": "stable", + "ring": 1 + } ] - }, - "patch": { - "description": "Updates (or adds when missing) tenant configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Tenant/:tenantId/Patch", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - } - ], - "requestBody": { - "content": { - "application/json": { - "examples": { - "Tenant Configuration Details": { - "description": "Example tenant configuration object.", - "summary": "Tenant Configuration", - "value": { - "alphaEnabled": false, - "channel": "stable", - "ring": 1 - } - } - }, - "schema": { - "type": "object", - "properties": { - "alphaEnabled": { - "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", - "examples": [ - false - ], - "type": "boolean" - }, - "channel": { - "description": "Name of the deploy channel.", - "examples": [ - "stable" - ], - "type": "string" - }, - "ring": { - "description": "Ring number that the client is a member of for the current chanel.", - "examples": [ - 1 - ], - "type": "integer" - } - }, - "examples": [ - { - "alphaEnabled": false, - "channel": "stable", - "ring": 1 - } - ] - } - } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Tenant Configuration Details": { + "description": "Example object returned on creation or update with tenantId set.", + "summary": "Tenant Configuration", + "value": { + "alphaEnabled": false, + "channel": "stable", + "ring": 1, + "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" } + } }, - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "Tenant Configuration Details": { - "description": "Example object returned on creation or update with tenantId set.", - "summary": "Tenant Configuration", - "value": { - "alphaEnabled": false, - "channel": "stable", - "ring": 1, - "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" - } - } - }, - "schema": { - "$ref": "#/components/schemas/Update.Shield.Tenant" - } - } - }, - "description": "OK" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } + "schema": { + "$ref": "#/components/schemas/Update.Shield.Tenant" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Upserts Specific Tenant Configuration", + "tags": ["SHIELD - Update"] + }, + "delete": { + "description": "Deletes configuration for the specific tenant.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", + "operationId": "/Api/Update/Shield/Tenant/:tenantId/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "204": { + "description": "Deleted Successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Deletes Specific Tenant Configuration", + "tags": ["SHIELD - Update"] + } + }, + "/Api/Tenant": { + "get": { + "description": "Retrieves the list of tenant records. Can use filter by parent ID limit the results. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", + "operationId": "/Api/Tenant/Get", + "parameters": [ + { + "$ref": "#/components/parameters/parentId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/TenantDetails" + }, + "examples": [ + [ + { + "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", + "displayName": "Contoso - R&D", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [] + } + ] + ] }, - "summary": "Upserts Specific Tenant Configuration", - "tags": [ - "SHIELD - Update" - ] + "examples": { + "Example List Of Multiple Tenant Records": { + "description": "Sample list of multiple tenant records in the database", + "summary": "Multiple Tenant Records", + "value": [ + { + "tenantId": "5d6e7f8a-9b0c-1d2e-3f4a-5b6c7d8e9f0a", + "displayName": "Contoso - Legal", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [ + "59673771-3b4f-4518-9187-aee8a51c8c07", + "47c42971-2dea-4553-a788-d29a42e3e867" + ] + }, + { + "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", + "displayName": "Contoso - R&D", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [ + "7e9ce415-32b2-4e7a-a920-d4dbaae022e3" + ] + } + ] + }, + "Example List Of Single Tenant Record": { + "description": "Example list of single tenant records which no user is authorized yet.", + "summary": "Single Tenant Records", + "value": [ + { + "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", + "displayName": "Contoso - R&D", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [] + } + ] + } + } + } }, - "delete": { - "description": "Deletes configuration for the specific tenant.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", - "operationId": "/Api/Update/Shield/Tenant/:tenantId/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" + "description": "OK" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves List of Tenant Records", + "tags": ["Tenant Records"] + } + }, + "/Api/Tenant/{tenantId}": { + "get": { + "description": "Retrieves details of a specific tenant record. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", + "operationId": "/Api/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/parentId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenantDetails" + }, + "examples": { + "Example Complete Tenant Record": { + "description": "An example showing a single existing tenant record.", + "summary": "Existing Tenant Record", + "value": { + "tenantId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", + "displayName": "Contoso - Testing", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [ + "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", + "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b", + "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e" + ] } - ], - "responses": { - "204": { - "description": "Deleted Successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" + } + } + } + }, + "description": "OK" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Tenant Record", + "tags": ["Tenant Records"] + }, + "patch": { + "description": "Update tenant record using provided information. Payload could contain any combination of existing properties. To remove a parent, set the parentId to be the same as the tenant ID value. This endpoint requires the `Tenant.ReadWrite.All` scopes (permissions).", + "operationId": "/Api/Tenant/:tenantId/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "tenantDisplayName": { + "description": "Human readable name for the tenant record", + "type": "string", + "examples": ["Contoso - R&D East"] + }, + "parentId": { + "description": "The object ID of the tenant that is considered a parent to this record", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string", + "examples": ["6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d"] + }, + "authorizedPrincipalList": { + "description": "List of object IDs that are allowed to access this record and related data.", + "type": "array", + "items": { + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string", + "examples": ["4cae3355-0cff-410c-b4f9-69cb5de8f1ac"] }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } + "examples": [ + [ + "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", + "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" + ] + ] + } }, - "summary": "Deletes Specific Tenant Configuration", - "tags": [ - "SHIELD - Update" + "anyOf": [ + { + "required": ["displayName"] + }, + { + "required": ["parentId"] + }, + { + "required": ["authorizedPrincipalList"] + } + ], + "examples": [ + { + "tenantDisplayName": "Contoso - R&D East", + "parentId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d", + "authorizedPrincipalList": [ + "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", + "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" + ] + } ] + }, + "examples": { + "Example Request to Update Tenant Parent": { + "description": "Sample payload requesting adjustment to the parent value.", + "summary": "Update Parent Information for Tenant", + "value": { + "parentId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" + } + }, + "Example Request for Tenant Name and Parent Update": { + "description": "Sample payload requesting to update parent value and display name on the tenant record.", + "summary": "Update Tenant Record Name and Parent Information", + "value": { + "parentId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", + "displayName": "Contoso - R&D West" + } + }, + "Example Request for Tenant Authorized Principals Update": { + "description": "Sample payload requesting to update authorized principals for the tenant record.", + "summary": "Update Tenant Authorized Principals List", + "value": { + "authorizedPrincipalList": [ + "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", + "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" + ] + } + } + } } + } }, - "/Api/Tenant": { - "get": { - "description": "Retrieves the list of tenant records. Can use filter by parent ID limit the results. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", - "operationId": "/Api/Tenant/Get", - "parameters": [ - { - "$ref": "#/components/parameters/parentId" + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenantDetails" + }, + "examples": { + "Example Complete Tenant Record": { + "description": "Sample response after updating a tenant record.", + "summary": "Updated Tenant Record", + "value": { + "tenantId": "c00ffc2c-b6f6-4121-bd8e-4d02e9504eb9", + "displayName": "Contoso - Testing", + "parentId": "8c291062-a4f7-4706-b4df-59e605497f06", + "authorizedPrincipalList": [ + "b856517a-2086-4be4-b63e-d6ca8a5b0ff6" + ] } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "array", - "minItems": 0, - "items": { - "$ref": "#/components/schemas/TenantDetails" - }, - "examples": [ - [ - { - "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", - "displayName": "Contoso - R&D", - "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", - "authorizedPrincipalList": [] - } - ] - ] - }, - "examples": { - "Example List Of Multiple Tenant Records": { - "description": "Sample list of multiple tenant records in the database", - "summary": "Multiple Tenant Records", - "value": [ - { - "tenantId": "5d6e7f8a-9b0c-1d2e-3f4a-5b6c7d8e9f0a", - "displayName": "Contoso - Legal", - "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", - "authorizedPrincipalList": [ - "59673771-3b4f-4518-9187-aee8a51c8c07", - "47c42971-2dea-4553-a788-d29a42e3e867" - ] - }, - { - "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", - "displayName": "Contoso - R&D", - "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", - "authorizedPrincipalList": [ - "7e9ce415-32b2-4e7a-a920-d4dbaae022e3" - ] - } - ] - }, - "Example List Of Single Tenant Record": { - "description": "Example list of single tenant records which no user is authorized yet.", - "summary": "Single Tenant Records", - "value": [ - { - "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", - "displayName": "Contoso - R&D", - "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", - "authorizedPrincipalList": [] - } - ] - } - } - } - }, - "description": "OK" - }, - "404": { - "$ref": "#/components/responses/404" + } + } + } + }, + "description": "OK" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Update Tenant Record", + "tags": ["Tenant Records"] + } + }, + "/Api/ArchitectureReport": { + "post": { + "description": "A route to store a new architectural analysis report information.", + "operationId": "/Api/ArchitectureReport/Post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReport" + }, + "examples": { + "Sample Architecture Report Upload": { + "summary": "The architecture report being uploaded.", + "description": "An example architecture report object upload to the endpoint for storage.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + }, + "scheduling": "2023-02-04T05:06:09.601Z", + "securityPosture": { + "device": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + }, + "user": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + } }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 0, + "totalMemberCount": 1, + "totalUserCount": 1 } - }, - "summary": "Retrieves List of Tenant Records", - "tags": [ - "Tenant Records" - ] + } + } + } } + } }, - "/Api/Tenant/{tenantId}": { - "get": { - "description": "Retrieves details of a specific tenant record. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", - "operationId": "/Api/Tenant/:tenantId/Get", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - }, - { - "$ref": "#/components/parameters/parentId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TenantDetails" - }, - "examples": { - "Example Complete Tenant Record": { - "description": "An example showing a single existing tenant record.", - "summary": "Existing Tenant Record", - "value": { - "tenantId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", - "displayName": "Contoso - Testing", - "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", - "authorizedPrincipalList": [ - "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", - "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b", - "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e" - ] - } - } - } + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReport" + }, + "examples": { + "Successful upload": { + "summary": "The Architecture Report Returned", + "description": "An example architecture report object returned indicating the architecture report upload operation succeed. This should be the same as the uploaded architecture report.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + }, + "scheduling": "2023-02-04T05:06:09.601Z", + "securityPosture": { + "device": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 } + } }, - "description": "OK" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Retrieves Tenant Record", - "tags": [ - "Tenant Records" - ] - }, - "patch": { - "description": "Update tenant record using provided information. Payload could contain any combination of existing properties. To remove a parent, set the parentId to be the same as the tenant ID value. This endpoint requires the `Tenant.ReadWrite.All` scopes (permissions).", - "operationId": "/Api/Tenant/:tenantId/Patch", - "parameters": [ - { - "$ref": "#/components/parameters/tenantId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "tenantDisplayName": { - "description": "Human readable name for the tenant record", - "type": "string", - "examples": [ - "Contoso - R&D East" - ] - }, - "parentId": { - "description": "The object ID of the tenant that is considered a parent to this record", - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string", - "examples": [ - "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" - ] - }, - "authorizedPrincipalList": { - "description": "List of object IDs that are allowed to access this record and related data.", - "type": "array", - "items": { - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string", - "examples": [ - "4cae3355-0cff-410c-b4f9-69cb5de8f1ac" - ] - }, - "examples": [ - [ - "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", - "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" - ] - ] - } - }, - "anyOf": [ - { - "required": [ - "displayName" - ] - }, - { - "required": [ - "parentId" - ] - }, - { - "required": [ - "authorizedPrincipalList" - ] - } - ], - "examples": [ - { - "tenantDisplayName": "Contoso - R&D East", - "parentId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d", - "authorizedPrincipalList": [ - "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", - "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" - ] - } - ] - }, - "examples": { - "Example Request to Update Tenant Parent": { - "description": "Sample payload requesting adjustment to the parent value.", - "summary": "Update Parent Information for Tenant", - "value": { - "parentId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" - } - }, - "Example Request for Tenant Name and Parent Update": { - "description": "Sample payload requesting to update parent value and display name on the tenant record.", - "summary": "Update Tenant Record Name and Parent Information", - "value": { - "parentId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", - "displayName": "Contoso - R&D West" - } - }, - "Example Request for Tenant Authorized Principals Update": { - "description": "Sample payload requesting to update authorized principals for the tenant record.", - "summary": "Update Tenant Authorized Principals List", - "value": { - "authorizedPrincipalList": [ - "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", - "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" - ] - } - } + "user": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 } + } } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 0, + "totalMemberCount": 1, + "totalUserCount": 1 + } } + } + } + } + }, + "description": "The uploaded architecture report has been stored successfully." + }, + "400": { + "$ref": "#/components/responses/400" + } + }, + "summary": "Store new architectural analysis report.", + "tags": ["Architecture Report"] + } + }, + "/Api/ArchitectureReport/Correlation": { + "get": { + "description": "A route to retrieve the list of correlation records for the current authenticated tenant.", + "operationId": "/Api/ArchitectureReport/Correlation/Get", + "parameters": [ + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/ArchitectureReport.ArchitectureCorrelationRecord" + }, + "minItems": 0, + "type": "array" }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TenantDetails" - }, - "examples": { - "Example Complete Tenant Record": { - "description": "Sample response after updating a tenant record.", - "summary": "Updated Tenant Record", - "value": { - "tenantId": "c00ffc2c-b6f6-4121-bd8e-4d02e9504eb9", - "displayName": "Contoso - Testing", - "parentId": "8c291062-a4f7-4706-b4df-59e605497f06", - "authorizedPrincipalList": [ - "b856517a-2086-4be4-b63e-d6ca8a5b0ff6" - ] - } - } - } - } - }, - "description": "OK" - }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } + "examples": { + "Returned Architecture Correlation Records": { + "summary": "Example Architecture Correlation Records returned", + "description": "An example of an ArchitectureReport.ArchitectureCorrelationRecord array returned.", + "value": [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + } + ] + } + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + } + }, + "summary": "Retrieve correlation records for current tenant.", + "tags": ["Architecture Report"] + } + }, + "/Api/ArchitectureReport/Correlation/Tenant/{tenantId}": { + "get": { + "description": "Internal API route to retrieve the list of correlation records for the specified tenant, if the caller is SHI and authorized.", + "operationId": "/Api/ArchitectureReport/Correlation/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/ArchitectureReport.ArchitectureCorrelationRecord" + }, + "minItems": 0, + "type": "array" }, - "summary": "Update Tenant Record", - "tags": [ - "Tenant Records" - ] - } - } + "examples": { + "Returned Architecture Correlation Records": { + "summary": "Example Architecture Correlation Records returned", + "description": "An example of an ArchitectureReport.ArchitectureCorrelationRecord array returned.", + "value": [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + } + ] + } + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + } + }, + "summary": "Retrieve correlation records for the specified tenant.", + "tags": ["Architecture Report"] + } }, - "security": [ - { - "EntraID": [] - } - ], - "servers": [ + "/Api/ArchitectureReport/Correlation/{correlationId}/Data": { + "parameters": [ { - "description": "Server the hosts the API described in the document.", - "url": "https://api.shilab.com" + "$ref": "#/components/parameters/correlationId" } - ], - "tags": [ - { - "description": "Routes for the core data gateway system.", - "name": "Core System", - "externalDocs": { - "description": "Data Gateway Documentation", - "url": "https://docs.shilab.com/Date-Gateway/" - } - }, - { - "description": "Manages the list of tenants that have interacted with the Data Gateway in the past.", - "name": "Tenant Records" + ], + "get": { + "description": "A route to retrieve architectural analysis report for the specified correlation ID in the authenticated tenant.", + "operationId": "/Api/ArchitectureReport/Correlation/:correlationId/Data/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReport" + }, + "examples": { + "Returned Architecture Report": { + "summary": "Example Architecture Report returned", + "description": "An example of ArchitectureReport object returned that represents an successful architectural analysis run result.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + }, + "scheduling": "2023-02-04T05:06:09.601Z", + "securityPosture": { + "device": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + }, + "user": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 0, + "totalMemberCount": 1, + "totalUserCount": 1 + } + } + } + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + } }, - { - "description": "Collects and reports data from the license analytics product.", - "name": "License Analytics", - "externalDocs": { - "description": "License Analytics Documentation", - "url": "https://docs.shilab.com/License-Analytics/" - } + "summary": "Retrieve architectural analysis report for current tenant by specified correlation ID.", + "tags": ["Architecture Report"] + }, + "delete": { + "description": "A route to allow customers to self service delete architectural analysis report.", + "operationId": "/Api/ArchitectureReport/Correlation/:correlationId/Data/Delete", + "responses": { + "204": { + "description": "The specified architectural analysis report has been deleted successfully." + }, + "400": { + "$ref": "#/components/responses/400" + } }, + "summary": "Delete specific architectural analysis report by correlation ID.", + "tags": ["Architecture Report"] + } + }, + "/Api/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data": { + "parameters": [ { - "description": "Manages and reports the list of purchased licenses for the various SHI Lab Products.", - "name": "License Entitlement" + "$ref": "#/components/parameters/correlationId" }, { - "description": "Collects data from the various SHI Lab products.", - "name": "Telemetry" + "$ref": "#/components/parameters/tenantId" + } + ], + "get": { + "description": "Internal API route to retrieve architectural analysis report for the specified correlation ID for the specified tenant, if the caller is SHI and authorized.", + "operationId": "/Api/ArchitectureReport/Correlation/:correlationId/Tenant/:tenantId/Data/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReport" + }, + "examples": { + "Returned Architecture Report": { + "summary": "Example Architecture Report returned", + "description": "An example of ArchitectureReport object returned that represents an successful architectural analysis run result.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-02-04T05:06:09.601Z", + "reportTenantAccount": "user@example.com", + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-02-04T05:06:09.601Z" + }, + "scheduling": "2023-02-04T05:06:09.601Z", + "securityPosture": { + "device": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + }, + "user": { + "123e4567-e89b-12d3-a456-426614174000": { + "assignedService": { + "234e4567-e89b-12d3-a456-426614174000": 0 + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 0, + "totalMemberCount": 1, + "totalUserCount": 1 + } + } + } + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + } }, - { - "name": "SHIELD - Update", - "description": "Update Service Configuration for SHIELD." + "summary": "Retrieve architectural analysis reports for the specified tenant by correlation ID.", + "tags": ["Architecture Report"] + }, + "delete": { + "description": "Internal API route to remove the specified architectural analysis report, if the caller is SHI and authorized.", + "operationId": "/Api/ArchitectureReport/Correlation/:correlationId/Tenant/:tenantId/Data/Delete", + "responses": { + "204": { + "description": "The specified architectural analysis report has been deleted successfully." + }, + "400": { + "$ref": "#/components/responses/400" + } }, - { - "name": "Chat", - "description": "Enables query for available information (like tenant, license, etc) via conversation with OpenAI agent." - } - ] + "summary": "Remove architectural analysis report for the specified tenant by correlation ID.", + "tags": ["Architecture Report"] + } + } + }, + "security": [ + { + "EntraID": [] + } + ], + "servers": [ + { + "description": "Server the hosts the API described in the document.", + "url": "https://api.shilab.com" + } + ], + "tags": [ + { + "description": "Routes for the core data gateway system.", + "name": "Core System", + "externalDocs": { + "description": "Data Gateway Documentation", + "url": "https://docs.shilab.com/Date-Gateway/" + } + }, + { + "description": "Manages the list of tenants that have interacted with the Data Gateway in the past.", + "name": "Tenant Records" + }, + { + "description": "Collects and reports data from the license analytics product.", + "name": "License Analytics", + "externalDocs": { + "description": "License Analytics Documentation", + "url": "https://docs.shilab.com/License-Analytics/" + } + }, + { + "description": "Manages and reports the list of purchased licenses for the various SHI Lab Products.", + "name": "License Entitlement" + }, + { + "description": "Collects data from the various SHI Lab products.", + "name": "Telemetry" + }, + { + "name": "SHIELD - Update", + "description": "Update Service Configuration for SHIELD." + }, + { + "name": "Chat", + "description": "Enables query for available information (like tenant, license, etc) via conversation with OpenAI agent." + } + ] } diff --git a/specs/SHIELD.json b/specs/SHIELD.json index c6752de..102e3b3 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -1,156 +1,1921 @@ { - "components": { - "parameters": { - "correlationId": { - "description": "The object ID of the correlation identifier for the specified record.", - "in": "path", - "name": "correlationId", - "required": true, - "schema": { - "examples": [ - "1d71e0fe-6e4a-464d-a690-80addf3bda55" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "components": { + "parameters": { + "correlationId": { + "description": "The object ID of the correlation identifier for the specified record.", + "in": "path", + "name": "correlationId", + "required": true, + "schema": { + "examples": ["1d71e0fe-6e4a-464d-a690-80addf3bda55"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "valid correlation ID": { + "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55", + "summary": "Example valid correlation ID", + "description": "An example of a valid correlation ID in type UUID." + } + } + }, + "deviceId": { + "description": "The SHIELD ID (Entra ID Device ID) of the managed device to target.", + "in": "path", + "name": "deviceId", + "required": true, + "schema": { + "examples": ["75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "valid device ID": { + "value": "75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51", + "summary": "Example valid device ID", + "description": "An example of a valid managed Entra ID device ID in type UUID." + } + } + }, + "intermediaryId": { + "description": "The Object ID of the parent group for the intermediary that you wish to target.", + "in": "path", + "name": "intermediaryId", + "required": true, + "schema": { + "examples": ["25d4d9da-28ea-42f8-b3df-23c3969abffa"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "valid intermediary ID": { + "value": "25d4d9da-28ea-42f8-b3df-23c3969abffa", + "summary": "Example intermediary ID", + "description": "An example of a valid parent group ID in type UUID." + } + } + }, + "nextLink": { + "description": "Information to be provided to the API call in order to retrieve next set of data as part of pagination. It could be a simple number or full URL representing MS Graph API navigation. This information should not be generated by hand or changed. In case of MS Graph API, please only use tokens the server gives you and do not bring them from outside.", + "in": "query", + "name": "nextLink", + "schema": { + "examples": ["3"], + "minLength": 1, + "type": "string" + }, + "examples": { + "Number": { + "value": "3", + "summary": "Number for the next page in the navigation flow", + "description": "The number representation with minimal length for the next page in the navigation flow." + }, + "Uri": { + "value": "https://graph.microsoft.com/beta/devices?$top=20&$skiptoken=RFNwdCtEZXZpY2VfMThkNGY4OTAtMDA2YS00ZWM1LWI2OWYtY2VmNDY4ZjczNzQ4K0RldmljZV8xOGQ0Zjg5MC0wMDZhLTRlYzUtYjY5Zi1jZWY0NjhmNzM3NDg", + "summary": "Complete URL with details of the request and a skip token for MS Graph to parse and respond.", + "description": "The uri representation for the next page in the navigation flow. This example shows the complete URL with details of the request and a skip token for MS Graph to parse and respond." + } + } + }, + "offeringId": { + "description": "Unique identifier of the marketplace offering", + "in": "path", + "name": "offeringId", + "required": true, + "schema": { + "description": "Unique identifier of the marketplace offering.", + "examples": ["271ab834-7469-4f2d-a705-549972c4f325"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "valid offering ID": { + "value": "271ab834-7469-4f2d-a705-549972c4f325", + "summary": "Example of an offering ID", + "description": "An example of an valid marketplace offering ID in type UUID." + } + } + }, + "search": { + "description": "Used in object filtering.", + "in": "query", + "name": "search", + "schema": { + "examples": ["finance"], + "type": "string" + }, + "examples": { + "valid search term": { + "value": "finance", + "summary": "Example search term", + "description": "An example valid search term used in object filtering in a query." + } + } + }, + "securityClass": { + "description": "The security class of managed object to retrieve. Unknown values, will be ignored. Please see https://learn.microsoft.com/en-us/security/compass/privileged-access-security-levels for a description of security levels.", + "in": "path", + "name": "securityClass", + "required": true, + "schema": { + "$ref": "#/components/schemas/SecurityClassList" + }, + "examples": { + "Privileged": { + "value": "Privileged", + "summary": "Example security class", + "description": "An example enum string that indicates the security class of an managed object is privileged." + } + } + }, + "updateChannelName": { + "description": "Name of the update channel that should be used when querying or downloading updates.", + "in": "path", + "name": "Update Channel Name", + "required": true, + "schema": { + "examples": ["stable"], + "type": "string", + "enum": ["alpha", "beta", "stable"] + }, + "examples": { + "valid channel name": { + "value": "stable", + "summary": "Example of an update channel name", + "description": "An example of an valid update channel name that should be used when querying or downloading updates." + } + } + }, + "userId": { + "description": "The SHIELD ID (Entra ID User's Object ID) of the managed user to target.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "examples": ["264a8bed-0714-48fd-8b9d-0e4c4715cee5"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "examples": { + "valid user ID": { + "value": "264a8bed-0714-48fd-8b9d-0e4c4715cee5", + "summary": "Example of a user ID", + "description": "An example of valid EntraID managed user ID in type UUID." + } + } + } + }, + "responses": { + "201": { + "description": "The authorization was recorded successfully." + }, + "202": { + "description": "The process to create a report has started." + }, + "400": { + "description": "Invalid input!" + }, + "401": { + "description": "Principal is not authorized to access this endpoint. Check to make sure the Bearer token is valid and present!" + }, + "403": { + "description": "Principal does not contain the correct scopes (permissions) for the API call that was made, or was made from the wrong tenant. If the permissions were granted, ensure that the access token was requested with the correct scopes." + }, + "404": { + "description": "The requested object was not found." + }, + "409": { + "description": "A job is already in progress." + }, + "525": { + "description": "Infrastructure not deployed. Please deploy the infrastructure before using this endpoint." + } + }, + "schemas": { + "Core.SystemRequirements": { + "title": "Core - System Requirements", + "description": "Collection of indicators that notify the caller if the system requirements have been met for various sub components to operate.", + "properties": { + "authenticatorPermissions": { + "description": "Flag that indicates if the core permissions for the SHIELD - Authenticator App have been configured properly or not.", + "type": "boolean", + "examples": [true] + }, + "azurePermissions": { + "description": "Flag that indicates if the required core Azure RBAC assignment(s) are present or not.", + "type": "boolean", + "examples": [false] + }, + "defendEntitlement": { + "description": "Flag that indicates if the required defend licenses are present or not.", + "type": "boolean", + "examples": [true] + }, + "deployEntitlement": { + "description": "Flag that indicates if the required deploy licenses are present or not.", + "type": "boolean", + "examples": [true] + }, + "discoverEntitlement": { + "description": "Flag that indicates if the required discover licenses are present or not.", + "type": "boolean", + "examples": [true] + }, + "msGraphPermissions": { + "description": "Flag that indicates if the core permissions for the Microsoft Graph API have been configured properly or not.", + "type": "boolean", + "examples": [false] + }, + "dataGatewayPermissions": { + "description": "Flag that indicates if the core permissions for the SHI - Data Gateway have been configured properly or not.", + "type": "boolean", + "examples": [false] + }, + "entraDirectoryRole": { + "description": "Flag that indicates if the core permissions for Entra Directory Role assignment have been configured properly or not.", + "type": "boolean", + "examples": [false] + } + }, + "type": "object", + "required": [ + "authenticatorPermissions", + "azurePermissions", + "defendEntitlement", + "deployEntitlement", + "discoverEntitlement", + "msGraphPermissions", + "dataGatewayPermissions", + "entraDirectoryRole" + ], + "examples": [ + { + "authenticatorPermissions": true, + "azurePermissions": false, + "defendEntitlement": true, + "deployEntitlement": false, + "discoverEntitlement": true, + "msGraphPermissions": false, + "dataGatewayPermissions": false, + "entraDirectoryRole": false + } + ] + }, + "Core.ProgressBar": { + "title": "Core - Progress Bar", + "description": "Used to indicate the progress of a long running operation.", + "properties": { + "childBar": { + "description": "Sub progress bar that should appear below the current progress bar for a dependent execution branch.", + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/Core.ProgressBar" + }, + "examples": [ + [ + { + "description": "Collecting data from the Microsoft Entra ID system.", + "displayName": "Running Entra ID Plugin", + "id": "b759230f-48cb-496e-ad57-5f079083226b", + "currentStep": 5, + "totalStepCount": 7 + } + ] + ] + }, + "description": { + "type": "string", + "description": "Long form text describing the current step.", + "examples": ["Collecting data from the Microsoft Entra ID system."] + }, + "displayName": { + "type": "string", + "description": "Text/label to render with the progress bar.", + "examples": ["Running Entra ID Plugin"] + }, + "id": { + "description": "Unique identifier to be able to select this specific instance via search.", + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": ["b759230f-48cb-496e-ad57-5f079083226b"] + }, + "currentStep": { + "description": "Current step/value for the progress bar. This is in relation to the `totalStepCount` property. If undefined, an indeterminate/pulsing progress bar is used instead.", + "examples": [5], + "type": "number" + }, + "totalStepCount": { + "description": "Number of steps before the progress bar is completely filed.", + "examples": [7], + "type": "number", + "minimum": 1 + } + }, + "type": "object", + "required": ["childBar", "displayName", "id", "totalStepCount"], + "examples": [ + { + "childBar": [], + "description": "Collecting data from the Microsoft Entra ID system.", + "displayName": "Running Entra ID Plugin", + "id": "b759230f-48cb-496e-ad57-5f079083226b", + "currentStep": 5, + "totalStepCount": 7 + } + ] + }, + "Authenticator.RequestStatus": { + "title": "Authentication - Status", + "description": "List of credentials that are being waited for by SHIELD's internal authentication engine.", + "properties": { + "accessToken": { + "oneOf": [ + { + "description": "Flag that represents if the server is not waiting for a specific access token.", + "type": "boolean", + "examples": [false] + }, + { + "$ref": "#/components/schemas/Authenticator.Status.TokenAudience" + } + ], + "examples": [ + false, + { "audience": "00000002-0000-0000-b000-000000000000" } + ] + }, + "sccAuth": { + "description": "Flag that represents if the server is waiting for SCC Auth credentials.", + "type": "boolean", + "examples": [true] + } + }, + "type": "object", + "required": ["accessToken", "sccAuth"], + "examples": [ + { + "accessToken": { + "audience": "00000002-0000-0000-b000-000000000000" + }, + "sccAuth": true + } + ] + }, + "Authenticator.Status.TokenAudience": { + "title": "SHIELD - Authenticator - Status - Token Audience", + "description": "If a access token is being requested, this is the audience that the access token should have when being submitted.", + "properties": { + "audience": { + "description": "Audience ID of the access token that is being requested.", + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": ["00000002-0000-0000-b000-000000000000"] + } + }, + "type": "object", + "required": ["audience"], + "examples": [ + { + "audience": "00000002-0000-0000-b000-000000000000" + } + ] + }, + "Authenticator.Container.SccAuthCredentials": { + "title": "SHIELD - Authenticator - SCC Auth", + "description": "SHIELD - Defender, and Purview portal Container Credentials", + "type": "object", + "properties": { + "authenticatedUpn": { + "description": "User principal name of the user that authenticated to the portals.", + "examples": ["user@example.com"], + "type": "string", + "format": "email" + }, + "expiration": { + "description": "Point in time at which the whole authentication structure has an expired state and is un-useable.", + "examples": ["2024-09-26T18:16:29.340Z"], + "type": "string", + "format": "date-time" + }, + "defender": { + "$ref": "#/components/schemas/Authenticator.Container.SccAuthCredentials.CredentialContainer" + }, + "security": { + "$ref": "#/components/schemas/Authenticator.Container.SccAuthCredentials.CredentialContainer" + }, + "purview": { + "$ref": "#/components/schemas/Authenticator.Container.SccAuthCredentials.CredentialContainer" + } + }, + "required": ["authenticatedUpn", "security", "purview"], + "examples": [ + { + "authenticatedUpn": "user@example.com", + "security": { + "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", + "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + }, + "purview": { + "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", + "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + }, + "expiration": "2024-09-26T18:16:29.340Z", + "defender": { + "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", + "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + } + } + ] + }, + "Authenticator.Container.SccAuthCredentials.CredentialContainer": { + "title": "SHIELD - Authenticator - SCC Auth - Credential Container", + "description": "Container for the credentials for a single SccAuth authenticated site.", + "properties": { + "sccAuth": { + "description": "Authentication token.", + "examples": [ + "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)" + ], + "type": "string" + }, + "xsrf": { + "description": "Cross Site Request Forgery Prevention Token.", + "examples": [ + "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + ], + "type": "string" + } + }, + "required": ["sccAuth", "xsrf"], + "type": "object", + "examples": [ + { + "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", + "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + } + ] + }, + "Discover.ExecutionStatus": { + "title": "Discover - Status", + "description": "Detailed status that indicates the current state of the Discover engine and its progress.", + "type": "object", + "properties": { + "running": { + "description": "Flag that indicates if another run is already in progress or not.", + "type": "boolean", + "examples": [true] + } + }, + "required": ["running"], + "examples": [ + { + "running": true + } + ] + }, + "ManagedObject.Intermediary": { + "description": "Base template for all intermediary objects to inherit from.", + "properties": { + "id": { + "description": "Read-only.", + "examples": ["e097a3f5-9599-44a2-8923-fd3276c83ae1"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "kind": { + "description": "Type of Intermediary that the properties are describing.", + "examples": ["AVD"], + "type": "string" + }, + "name": { + "description": "Human friendly name of the AVD cluster. This will be displayed to end users in the remote desktop app and web portals.", + "examples": ["Legacy Reach Back"], + "maxLength": 42, + "minLength": 1, + "type": "string" + }, + "securityClass": { + "$ref": "#/components/schemas/SecurityClassList" + } + }, + "required": ["name"], + "title": "Intermediary - Base Type", + "type": "object", + "examples": [ + { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged" + } + ] + }, + "ManagedObject.AvdIntermediary": { + "properties": { + "addressRangeCIDR": { + "description": "Optional Virtual Network IP Address range, defaults to 10.0.0.0/16.", + "examples": ["172.16.1.0/24"], + "type": "string" + }, + "assignmentGroup": { + "description": "Read-only value that the server generates that is the Object ID of the user assignment security group for the current instance of the AVD intermediary.", + "examples": ["68873e26-3c35-465c-9422-0884a00beb36"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "index": { + "description": "Used to uniquely name multiple session hosts in a single host pool.", + "minimum": 0, + "type": "number", + "examples": [0] + }, + "location": { + "description": "Azure Regions that are available for the configured subscription. Resources will be deployed to the region specified here.", + "examples": ["East US 2"], + "type": "string" + }, + "resourceId": { + "description": "ID of the Host Pool. This is generated by the server and can't be set, hence the read only flag.", + "examples": [ + "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back" + ], + "minLength": 122, + "readOnly": true, + "type": "string" + }, + "sessionHostGroup": { + "description": "Read-only value that the server generates that is the Object ID of the session host security group for the current instance of the AVD intermediary.", + "examples": ["f99f0918-da9b-4c58-9a8d-9346abc5d9ec"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "sessionHostPrefix": { + "description": "Short name to append to the beginning of the session host VMs. The max computer name length is 15, 4 chars are reserved for indexing and 4 for prefixing.", + "examples": ["Reach"], + "maxLength": 7, + "minLength": 1, + "type": "string" + }, + "vmSku": { + "description": "SKU ID in Azure of the VM session host set that is to be deployed.", + "examples": ["Standard_D2s_v5"], + "type": "string" + } + }, + "required": ["index", "location", "sessionHostPrefix", "vmSku"], + "title": "Intermediary - Azure Virtual Desktop", + "type": "object", + "examples": [ + { + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + ] + }, + "LicenseReport.CorrelationRecord": { + "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", + "examples": [ + { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", + "reportTenantAccount": "ent-user@example.com", + "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", + "createdAt": "2024-08-01T21:13:12.821Z", + "updatedAt": "2024-08-01T21:13:12.821Z" + } + ], + "properties": { + "auditTenantAccount": { + "description": "The user account used to retrieve the license information in the tenant being audited.", + "examples": ["admin-user@example.com"], + "format": "email", + "type": "string" + }, + "correlationId": { + "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", + "examples": ["88da2253-758f-4135-9d37-64448c8b65c1"], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "reportTenantAccount": { + "description": "User account used to store/report the license report to the SHI Lab cloud service.", + "examples": ["generic-user@example.com"], + "format": "email", + "type": "string" + }, + "tenantId": { + "description": "Unique ID of customer's Microsoft tenant that the license report is for.", + "examples": ["0e1fe83f-a33f-4250-8546-225b8d45ae01"], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "createdAt": { + "description": "Timestamp of when the report was created.", + "examples": ["2024-08-01T21:12:22.148Z"], + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp of when the report was last updated.", + "examples": ["2024-08-01T21:12:22.148Z"], + "format": "date-time", + "type": "string" + } + }, + "required": ["auditTenantAccount"], + "title": "License Report - Correlation Record", + "type": "object" + }, + "LicenseReport.LicenseData": { + "type": "object", + "properties": { + "assignedLicense": { + "additionalProperties": { + "type": "integer", + "examples": [1] + }, + "description": "License assignment on the specified principal.", + "type": "object", + "examples": [ + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 1 + } + ] + }, + "assignedService": { + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" }, - "examples": { - "valid correlation ID": { - "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55", - "summary": "Example valid correlation ID", - "description": "An example of a valid correlation ID in type UUID." + { + "type": "integer", + "format": "int32", + "examples": [0] + } + ] + }, + "description": "Service configuration assignment. This is used to record the set of principals that are \"benefiting\" from the service, regardless of license status.", + "type": "object", + "examples": [ + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": false, + "Access Review": true, + "Entitlement Management": false, + "Identity Protection": true + } + }, + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0 + } + ] + }, + "consumedService": { + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" + }, + { + "type": "integer", + "format": "int32", + "examples": [0] + } + ] + }, + "description": "Usage telemetry retrieved for the service to indicate if the specific principal is consuming the service or not, regardless of license status.", + "type": "object", + "examples": [ + { + "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null + }, + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": true, + "Access Review": false, + "Entitlement Management": false, + "Identity Protection": true + } + } + ] + } + }, + "required": ["assignedLicense", "assignedService", "consumedService"], + "description": "Collection of principals that have had their in-use licenses and assigned licenses. Where the key is the principal ID and the value is the insights.", + "examples": [ + { + "assignedLicense": { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": null, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": null, + "7159f980-6f83-4b67-bf41-e172b3ae1352": null + }, + "assignedService": { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": false, + "Access Review": true, + "Entitlement Management": false, + "Identity Protection": true + }, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { + "Conditional Access": true, + "Dynamic Group": false, + "Group Naming": true, + "On-Prem SSPR": false, + "Group Expiration": true, + "Provisioning Engine": true, + "Enterprise State Roaming": false + }, + "6511755b-c27d-4c66-a59e-b835e6b54e7f": null + }, + "consumedService": { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": { + "Conditional Access": true, + "Access Review": false, + "Entitlement Management": false, + "Identity Protection": true + }, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { + "Conditional Access": true, + "Dynamic Group": false, + "Group Naming": true, + "On-Prem SSPR": false, + "Group Expiration": true, + "Provisioning Engine": true, + "Enterprise State Roaming": false + }, + "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null, + "c90f1a25-e6cd-4163-ac6c-ca7616c585a9": null + } + } + ], + "title": "License Report - License Data" + }, + "LicenseReport.FeatureBreakdown": { + "additionalProperties": { + "type": "boolean", + "examples": [true] + }, + "description": "List of features that are configured for the specific service plan's service configuration for the related principal.\nThe key is the name of the feature that is being described.\nThe value is the state of the feature configuration, `true` is in scope and `false` meaning not in scope.", + "examples": [ + { + "Conditional Access": true, + "Access Reviews": true, + "Dynamic Groups": false, + "On-Prem Password Rest": true, + "On-Prem Password Protection": false + } + ], + "title": "License Report - Feature Breakdown", + "type": "object" + }, + "LicenseReport": { + "description": "Completely calculated license report structure that is the result of a complete run.", + "examples": [ + { + "availableLicense": { + "e17b13ee-9749-488b-9289-d31a8fde045d": 123, + "2d995b6a-d4aa-4d8d-a03c-372ecb66509d": 456, + "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 789 + }, + "correlation": { + "auditTenantAccount": "admin-user@example.com", + "correlationId": "88da2253-758f-4135-9d37-64448c8b65c1", + "reportTenantAccount": "generic-user@example.com", + "tenantId": "0e1fe83f-a33f-4250-8546-225b8d45ae01" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "e17b13ee-9749-488b-9289-d31a8fde045d": null + }, + "assignedService": { + "cbf6ee7c-c3c1-44a6-9f18-020c65536470": null, + "c7bcba35-199c-41e5-8c8d-6d4e4aad8964": null + }, + "consumedService": { + "fe98c41a-d931-4f6f-a5bc-750ba7144a77": null, + "0474bdf1-ee76-4aff-a65c-6f82e5e1d5a6": { + "Something Here": true, + "Other Obscure feature": false + } + } + } + } + } + ], + "type": "object", + "properties": { + "availableLicense": { + "additionalProperties": { + "examples": [1234], + "type": "integer" + }, + "description": "Breakdown of the purchased licenses/service plans available in the tenant being audited for this run. Where the key is the ID of the service plan and the value is how many licenses are available/purchase for it.", + "examples": [ + { + "eec0eb4f-6444-4f95-aba0-50c24d67f998": 1234, + "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 123 + } + ], + "title": "License Report - Available Licenses", + "type": "object" + }, + "correlation": { + "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + }, + "licenseData": { + "additionalProperties": { + "$ref": "#/components/schemas/LicenseReport.LicenseData" + } + } + }, + "required": ["availableLicense", "correlation", "licenseData"], + "title": "License Report - Complete Object" + }, + "ManagedObject.Device": { + "title": "Managed Device", + "description": "Structure that represents a all of the states a managed device could be in.", + "type": "object", + "examples": [ + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + } + ], + "properties": { + "commissionedDate": { + "description": "This is the ISO 8601 string format of the time representing the commission date of the PAW.", + "examples": ["2023-02-04T05:06:09.601Z"], + "format": "date-time", + "type": "string" + }, + "displayName": { + "description": "Current computer name of the device according to Entra ID. Empty string indicates that the device has not joined Entra ID yet.", + "examples": ["Priv-01534962354"], + "maxLength": 15, + "minLength": 0, + "type": "string" + }, + "id": { + "description": "Entra ID Device ID (Not Object ID) of the specified device.", + "examples": ["9f237e13-9a04-4daf-b3d4-6d2beec3c2bf"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "parentDeviceId": { + "description": "DeviceID of the parent PAW device.", + "examples": ["81682cf5-0405-491d-8ab8-e07c778d7eaf"], + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "securityClass": { + "$ref": "#/components/schemas/SecurityClassList" + }, + "uniqueGroupId": { + "description": "The object ID of the unique security group that contains the managed Entra ID Device Identity.", + "examples": ["146964e0-8ca4-4af0-9c2a-894b32912463"], + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + } + }, + "required": [ + "commissionedDate", + "displayName", + "id", + "securityClass", + "uniqueGroupId" + ] + }, + "ManagedObject.PrivilegedDevice": { + "description": "Set of properties that are available on privileged managed device objects only.", + "title": "Managed Device - Privileged", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ManagedObject.Device" + }, + { + "type": "object", + "properties": { + "groupAssignmentId": { + "description": "This is the ID of the Custom CSP Device Configuration that configures the local admin and local hyper-v group memberships.", + "examples": ["830d8b6f-2f6f-41f7-8800-0c07445abd36"], + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "securityClass": { + "$ref": "#/components/schemas/SecurityClassList" + }, + "userAssignmentId": { + "description": "The ID of the Settings Catalog that contains the user rights assignment of the specified PAW device.", + "examples": ["146964e0-8ca4-4af0-9c2a-894b32912463"], + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "userAssignmentList": { + "description": "List of Object IDs for the privileged user accounts that are assigned to this device.", + "examples": [ + [ + "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", + "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", + "c54d4854-9254-4689-8a22-1cc80a3dae4e" + ] + ], + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + } + }, + "required": [ + "groupAssignmentId", + "securityClass", + "userAssignmentId", + "userAssignmentList" + ], + "examples": [ + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", + "securityClass": "Privileged", + "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "userAssignmentList": [ + "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", + "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", + "c54d4854-9254-4689-8a22-1cc80a3dae4e" + ] + } + ] + } + ] + }, + "ManagedObject.User": { + "title": "Managed User", + "description": "A user object that has limited properties. The user object is generated by combining multiple pieces of metadata from Entra ID and SHIELD.", + "properties": { + "creationDate": { + "description": "A date object representing when the user managed by SHIELD.", + "examples": ["2023-10-21T15:24:47.970Z"], + "format": "date-time", + "readOnly": true, + "type": "string" + }, + "displayName": { + "description": "The name shown on UIs for the privileged user according to Entra ID.", + "examples": ["Example User (Priv)"], + "maxLength": 256, + "type": "string" + }, + "firstName": { + "description": "Given name of the privileged user according to Entra ID.", + "maxLength": 64, + "type": "string", + "examples": ["John"] + }, + "id": { + "description": "The Entra ID Object ID of the managed user. This is the one property that is stored in the settings engine. This is the key in the storage systems to uniquely separate the managed user's data from others.", + "examples": ["9f237e13-9a04-4daf-b3d4-6d2beec3c2bf"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "intermediaryAssignmentList": { + "type": "array", + "description": "List of intermediaries that the user is assigned to.", + "items": { + "type": "string", + "format": "uuid" + }, + "examples": [ + [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + ] + }, + "lastName": { + "description": "Surname/family name of the privileged user according to Entra ID.", + "maxLength": 64, + "type": "string", + "examples": ["Doe"] + }, + "upn": { + "description": "User principal name of the user object according to Azure Active Directory.", + "examples": ["priv-user@example.com"], + "format": "email", + "maxLength": 113, + "minLength": 6, + "type": "string" + }, + "securityClass": { + "$ref": "#/components/schemas/SecurityClassList" + }, + "siloAssignmentList": { + "type": "array", + "description": "List of silos that the user is assigned to.", + "items": { + "type": "string", + "format": "uuid" + }, + "examples": [ + [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + ] + }, + "uiEducation": { + "description": "Indicates if user education is enabled in the UI for the specified user. True is on, false is off.", + "examples": [false], + "type": "boolean" + }, + "uniqueGroupId": { + "description": "ObjectID of the unique user group that the managed user is a member of.", + "examples": ["ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d"], + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + } + }, + "required": [ + "creationDate", + "securityClass", + "id", + "intermediaryAssignmentList", + "siloAssignmentList", + "uiEducation", + "uniqueGroupId", + "upn" + ], + "type": "object", + "examples": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + } + ] + }, + "ManagedObject.PrivilegedUser": { + "title": "Managed User - Privileged", + "description": "Additional settings that represents a privileged user object. All data in this structure is preserved in the settings engine's permanent storage system.", + "allOf": [ + { + "$ref": "#/components/schemas/ManagedObject.User" + }, + { + "properties": { + "deviceAssignmentList": { + "type": "array", + "description": "List of devices that the privileged users are able to use as endpoints.", + "items": { + "type": "string", + "format": "uuid" + }, + "examples": [ + [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + ] + }, + "generatedPassword": { + "description": "The password that was created for the managed user upon managed user creation, this is not stored. This is only available once during user creation. If the password is lost, reset the PWD in Entra ID or have the user perform SSPR.", + "examples": ["GY_w7bZUKRgpIXctD0S2wg"], + "readOnly": true, + "type": "string" + }, + "parentId": { + "description": "The Entra ID Object ID of the object that the manged user is tied to. This value is only present on privileged users.", + "examples": ["e59a3a64-dc36-4368-80ec-c205eb176ef6"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "readOnly": true, + "type": "string" + }, + "securityClass": { + "$ref": "#/components/schemas/SecurityClassList" + }, + "temporaryAccessPass": { + "description": "A TAP that was created for the managed user upon managed user creation, this is not stored. This is only available once during user creation. TAP expires at the configured tenant expiration time.", + "examples": ["BCKTSN#E2R&5"], + "readOnly": true, + "type": "string" + } + }, + "required": ["deviceAssignmentList", "parentId", "securityClass"], + "type": "object" + } + ], + "examples": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "deviceAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", + "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", + "temporaryAccessPass": "BCKTSN#E2R&5" + } + ] + }, + "ObjectPage.Intermediary.Avd": { + "properties": { + "@odata.count": { + "type": "number", + "examples": [0] + }, + "@odata.nextLink": { + "type": "string", + "examples": ["3"] + }, + "value": { + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/ManagedObject.Intermediary" + }, + { + "properties": { + "properties": { + "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" } + }, + "type": "object" } + ] }, - "deviceId": { - "description": "The SHIELD ID (Entra ID Device ID) of the managed device to target.", - "in": "path", - "name": "deviceId", - "required": true, + "minItems": 0, + "type": "array", + "examples": [ + { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged", + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + ] + } + }, + "examples": [ + { + "@odata.count": 1, + "@odata.nextLink": "1", + "value": [ + { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged", + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + ] + } + ], + "required": ["value"], + "title": "Page of AVD Intermediary Objects", + "type": "object" + }, + "ObjectPage.ManagedDevice": { + "properties": { + "@odata.count": { + "type": "number", + "examples": [3] + }, + "@odata.nextLink": { + "type": "string", + "examples": ["2"] + }, + "value": { + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/ManagedObject.Device" + }, + { + "$ref": "#/components/schemas/ManagedObject.PrivilegedDevice" + } + ] + }, + "minItems": 0, + "type": "array", + "examples": [ + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + }, + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", + "securityClass": "Privileged", + "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "userAssignmentList": [ + "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", + "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", + "c54d4854-9254-4689-8a22-1cc80a3dae4e" + ] + } + ] + } + }, + "required": ["value"], + "title": "Page of Managed Device Objects", + "type": "object", + "examples": [ + { + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + }, + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", + "securityClass": "Privileged", + "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "userAssignmentList": [ + "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", + "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", + "c54d4854-9254-4689-8a22-1cc80a3dae4e" + ] + } + ] + } + ] + }, + "ObjectPage.ManagedUser": { + "properties": { + "@odata.count": { + "type": "number", + "examples": [3] + }, + "@odata.nextLink": { + "type": "string", + "examples": ["2"] + }, + "value": { + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/ManagedObject.User" + }, + { + "$ref": "#/components/schemas/ManagedObject.PrivilegedUser" + } + ] + }, + "minItems": 0, + "type": "array", + "examples": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + }, + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "deviceAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", + "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", + "temporaryAccessPass": "BCKTSN#E2R&5" + } + ] + } + }, + "required": ["value"], + "title": "Page of Managed User Objects", + "type": "object", + "examples": [ + { + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + }, + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "deviceAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", + "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", + "temporaryAccessPass": "BCKTSN#E2R&5" + } + ] + } + ] + }, + "SecurityClassList": { + "description": "Security class types as described in https://learn.microsoft.com/en-us/security/compass/privileged-access-security-levels.", + "enum": ["Privileged", "Specialized", "Enterprise", "Unmanaged"], + "examples": ["Privileged"], + "title": "Type of security class the object(s) belongs to", + "type": "string" + } + }, + "securitySchemes": { + "EntraID": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT", + "description": "The Access Token from Entra ID for the `SHIELD - End User Login` Enterprise App (may need to be created from the App Registration)." + } + } + }, + "externalDocs": { + "description": "Official Documentation", + "url": "https://docs.shilab.com" + }, + "info": { + "contact": { + "email": "elliot_huffman@shi.com", + "name": "SHI - Lab" + }, + "description": "Deprive your threats of practical significance. Deploy the Securing Privilege Access architecture. All in a few seconds.", + "title": "SHI Environment Lockdown and Defense", + "version": "3.0.4" + }, + "openapi": "3.1.0", + "paths": { + "/Api/Core/SystemRequirements": { + "get": { + "description": "Provides a detailed breakdown of if the system requirements are being met for the various components of the SHIELD.", + "operationId": "/Api/Core/SystemRequirements/Get", + "responses": { + "200": { + "content": { + "application/json": { "schema": { - "examples": [ - "75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "$ref": "#/components/schemas/Core.SystemRequirements" }, "examples": { - "valid device ID": { - "value": "75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51", - "summary": "Example valid device ID", - "description": "An example of a valid managed Entra ID device ID in type UUID." - } + "System Requirement": { + "value": { + "authenticatorPermissions": true, + "azurePermissions": false, + "defendEntitlement": true, + "deployEntitlement": false, + "discoverEntitlement": true, + "msGraphPermissions": false, + "dataGatewayPermissions": false, + "entraDirectoryRole": false + }, + "summary": "Example system requirement object returned form the API endpoint", + "description": "An example that indicates:
- Azure RBAC assignment(s) are not present.
- SHIELD Defend licenses are present.
- SHIELD Deploy licenses are present.
- SHIELD Discover licenses are present.
- Permissions for the Microsoft Graph API have not been configured properly.
- Permissions for the SHI - Data Gateway have not been configured properly.
- Permissions for Entra Directory Role assignment have not been configured properly." + } } + } }, - "intermediaryId": { - "description": "The Object ID of the parent group for the intermediary that you wish to target.", - "in": "path", - "name": "intermediaryId", - "required": true, + "description": "OK" + } + }, + "tags": ["Core"], + "security": [], + "summary": "Indicates if the System Requirements are met or not." + } + }, + "/Api/Auth/Id": { + "get": { + "description": "Provides the Tenant ID and the Application ID of the service principal that access tokens need to be issued against. This is also useful for configuring public clients to be able to authenticate to for auth code flows.", + "operationId": "/Api/Auth/Id/Get", + "responses": { + "200": { + "content": { + "application/json": { "schema": { - "examples": [ - "25d4d9da-28ea-42f8-b3df-23c3969abffa" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "properties": { + "appId": { + "description": "Application ID that should be used in Access Tokens as the audience and the endpoint necessary for auth code flows.", + "type": "string", + "format": "uuid", + "examples": ["85cbe72b-3215-48bc-9eeb-fa7896c31498"] + }, + "tenantId": { + "description": "Tenant ID necessary for authority host URL configuration and UI customization.", + "type": "string", + "format": "uuid", + "examples": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"] + } + }, + "type": "object", + "required": ["appId", "tenantId"] }, "examples": { - "valid intermediary ID": { - "value": "25d4d9da-28ea-42f8-b3df-23c3969abffa", - "summary": "Example intermediary ID", - "description": "An example of a valid parent group ID in type UUID." - } + "valid request": { + "value": { + "appId": "85cbe72b-3215-48bc-9eeb-fa7896c31498", + "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + }, + "summary": "Example request object", + "description": "An example request object to retrieve the IDs required to authenticate." + } } + } }, - "nextLink": { - "description": "Information to be provided to the API call in order to retrieve next set of data as part of pagination. It could be a simple number or full URL representing MS Graph API navigation. This information should not be generated by hand or changed. In case of MS Graph API, please only use tokens the server gives you and do not bring them from outside.", - "in": "query", - "name": "nextLink", + "description": "OK" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "tags": ["Authentication"], + "security": [], + "summary": "Retrieves the IDs required to authenticate." + } + }, + "/Api/Auth/Authenticator": { + "get": { + "summary": "Provides Attestation for Authenticator App", + "description": "Provides the attestation to the authenticator that this endpoint is authorized for receiving credentials from the authenticator.\n\nThis endpoint requires the `Authentication.Actions.Attest`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Auth/Authenticator/GetAttest", + "responses": { + "200": { + "content": { + "text/plain": { "schema": { - "examples": [ - "3" - ], - "minLength": 1, - "type": "string" + "description": "Access token that SHIELD uses to prove it is a valid recipient of credentials.", + "type": "string", + "examples": [ + "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1jN2wzSXo5M2c3dXdnTmVFbW13X1dZR1BrbyJ9.eyJhdWQiOiJjYjU5ZjIyOC0wNjkwLTRhY2ItOWE3Yi0wMGMzNmEyZjRlOGQiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vMmQxMDJkYTktZDExZS00YTgwLTkwMjItYzQxOGZhNDg1NGM3L3YyLjAiLCJpYXQiOjE3MjczNjgzODQsIm5iZiI6MTcyNzM2ODM4NCwiZXhwIjoxNzI3MzcyMjg0LCJhaW8iOiJBU1FBMi84WUFBQUFSN0hyaW5XTmRwcisvdnoreWlkZER6WVExeFRpc3BSZGY4TG1XNjhRaE0wPSIsImF6cCI6IjRlODU5MTQ2LWY5M2UtNDlmMi05ODZmLWI3MjIyNmZjZDViOSIsImF6cGFjciI6IjEiLCJvaWQiOiJlMmRlNzQ0ZC1hZjVlLTQ4NDEtYmI4Zi02OTRkZDI1ZmVmNGQiLCJyaCI6IjAuQWNvQXFTMFFMUjdSZ0VxUUlzUVkta2hVeHlqeVdjdVFCc3RLbW5zQXcyb3ZUbzM2QUFBLiIsInJvbGVzIjpbIkF1dGhlbnRpY2F0b3IuQXR0ZXN0Il0sInN1YiI6ImUyZGU3NDRkLWFmNWUtNDg0MS1iYjhmLTY5NGRkMjVmZWY0ZCIsInRpZCI6IjJkMTAyZGE5LWQxMWUtNGE4MC05MDIyLWM0MThmYTQ4NTRjNyIsInV0aSI6Il9MaUdVWWxmS2txNFZoR09NeGw4QUEiLCJ2ZXIiOiIyLjAifQ.xlXZfOnDoOVW3_aOiSIZH8uiySeohro-HVnDzDEff2EjmOk9adrTOP5Sw1av6g3vy38r6dSu4tViwNGrb7Z2krgRKKvp-4A9rkPqeJjjd2rhFl2KiOlxL0mmykbroZZ70RJzwHy2GC7wfuLwJwr-5m7POV2grbxIAlTsMdZWDFXYi-AahfDVtLugarWG5-tXAqiPBKjaU6ntAJIbu7Ol1vYZaeYMsNKTs8O1P10YM460zN9OkfoI1gV7_InHEr8RSyQnEPCJ2W1Or4lDhqdey4ohMoP9EzLgMsn9Ckss5g5C6vVE0GQawUoeGozPOBpgb31J8JzZUyB1JyVfi-vKkQ" + ] }, "examples": { - "Number": { - "value": "3", - "summary": "Number for the next page in the navigation flow", - "description": "The number representation with minimal length for the next page in the navigation flow." - }, - "Uri": { - "value": "https://graph.microsoft.com/beta/devices?$top=20&$skiptoken=RFNwdCtEZXZpY2VfMThkNGY4OTAtMDA2YS00ZWM1LWI2OWYtY2VmNDY4ZjczNzQ4K0RldmljZV8xOGQ0Zjg5MC0wMDZhLTRlYzUtYjY5Zi1jZWY0NjhmNzM3NDg", - "summary": "Complete URL with details of the request and a skip token for MS Graph to parse and respond.", - "description": "The uri representation for the next page in the navigation flow. This example shows the complete URL with details of the request and a skip token for MS Graph to parse and respond." - } + "valid access token": { + "value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1jN2wzSXo5M2c3dXdnTmVFbW13X1dZR1BrbyJ9.eyJhdWQiOiJjYjU5ZjIyOC0wNjkwLTRhY2ItOWE3Yi0wMGMzNmEyZjRlOGQiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vMmQxMDJkYTktZDExZS00YTgwLTkwMjItYzQxOGZhNDg1NGM3L3YyLjAiLCJpYXQiOjE3MjczNjgzODQsIm5iZiI6MTcyNzM2ODM4NCwiZXhwIjoxNzI3MzcyMjg0LCJhaW8iOiJBU1FBMi84WUFBQUFSN0hyaW5XTmRwcisvdnoreWlkZER6WVExeFRpc3BSZGY4TG1XNjhRaE0wPSIsImF6cCI6IjRlODU5MTQ2LWY5M2UtNDlmMi05ODZmLWI3MjIyNmZjZDViOSIsImF6cGFjciI6IjEiLCJvaWQiOiJlMmRlNzQ0ZC1hZjVlLTQ4NDEtYmI4Zi02OTRkZDI1ZmVmNGQiLCJyaCI6IjAuQWNvQXFTMFFMUjdSZ0VxUUlzUVkta2hVeHlqeVdjdVFCc3RLbW5zQXcyb3ZUbzM2QUFBLiIsInJvbGVzIjpbIkF1dGhlbnRpY2F0b3IuQXR0ZXN0Il0sInN1YiI6ImUyZGU3NDRkLWFmNWUtNDg0MS1iYjhmLTY5NGRkMjVmZWY0ZCIsInRpZCI6IjJkMTAyZGE5LWQxMWUtNGE4MC05MDIyLWM0MThmYTQ4NTRjNyIsInV0aSI6Il9MaUdVWWxmS2txNFZoR09NeGw4QUEiLCJ2ZXIiOiIyLjAifQ.xlXZfOnDoOVW3_aOiSIZH8uiySeohro-HVnDzDEff2EjmOk9adrTOP5Sw1av6g3vy38r6dSu4tViwNGrb7Z2krgRKKvp-4A9rkPqeJjjd2rhFl2KiOlxL0mmykbroZZ70RJzwHy2GC7wfuLwJwr-5m7POV2grbxIAlTsMdZWDFXYi-AahfDVtLugarWG5-tXAqiPBKjaU6ntAJIbu7Ol1vYZaeYMsNKTs8O1P10YM460zN9OkfoI1gV7_InHEr8RSyQnEPCJ2W1Or4lDhqdey4ohMoP9EzLgMsn9Ckss5g5C6vVE0GQawUoeGozPOBpgb31J8JzZUyB1JyVfi-vKkQ", + "summary": "Example valid access token", + "description": "An example string that represents the access token that SHIELD uses to prove it is a valid recipient of credentials." + } } + } }, - "offeringId": { - "description": "Unique identifier of the marketplace offering", - "in": "path", - "name": "offeringId", - "required": true, + "description": "OK" + } + }, + "tags": ["Authentication"] + } + }, + "/Api/Auth/Authenticator/Cache/Status": { + "get": { + "summary": "Indicates if SHIELD is waiting for any credentials.", + "description": "Provides a breakdown view of if SHIELD is waiting for any specific type of credential or credentials.\n\nThis endpoint requires the `Authentication.Read`, `Authentication.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Auth/Authenticator/Cache/Status/Get", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Waiting on Nothing": { + "summary": "Not waiting for credentials", + "description": "No credentials are being requested at the moment.", + "value": { + "accessToken": false, + "sccAuth": false + } + }, + "Waiting on Access Token": { + "summary": "Waiting on access token", + "description": "Waiting on an Access Token with the Audience of the Legacy Windows Graph API.", + "value": { + "accessToken": { + "audience": "00000002-0000-0000-c000-000000000000" + }, + "sccAuth": false + } + }, + "Waiting on SccAuth": { + "summary": "Waiting on an SCC Auth data", + "description": "Waiting on an SCC Auth data from the SHIELD - Authenticator App.", + "value": { + "accessToken": false, + "sccAuth": true + } + } + }, "schema": { - "description": "Unique identifier of the marketplace offering.", + "$ref": "#/components/schemas/Authenticator.RequestStatus" + } + } + }, + "description": "OK" + } + }, + "tags": ["Authentication"] + } + }, + "/Api/Auth/Authenticator/Cache/SccAuth": { + "post": { + "description": "Configure SHIELD to use the specific SCC Auth credentials from the authenticator app to run web requests on behalf of the end user.\n\nThis endpoint requires the `Authentication.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Auth/Authenticator/Cache/SccAuth/Post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authenticator.Container.SccAuthCredentials" + }, + "examples": { + "valid Scc Auth credentials": { + "value": { + "authenticatedUpn": "user@example.com", + "security": { + "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", + "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + }, + "purview": { + "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", + "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + }, + "expiration": "2024-09-26T18:16:29.340Z", + "defender": { + "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", + "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" + } + }, + "summary": "Example Scc Auth credentials", + "description": "An example of valid Scc Auth credentials used to configure SHIELD." + } + } + } + } + }, + "responses": { + "204": { + "description": "Credential was successfully stored" + } + }, + "summary": "Provide Your SHIELD Authenticator Credentials - SCC Auth", + "tags": ["Authentication"] + } + }, + "/Api/Auth/Authenticator/Cache/AccessToken": { + "post": { + "summary": "Provide Your SHIELD Authenticator Credentials - Access Token", + "description": "Configure SHIELD to use the specific Access Token credentials from the authenticator app to run web requests on behalf of the end user.\n\nThis endpoint requires the `Authentication.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Auth/Authenticator/Cache/AccessToken/Post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Access Token to be stored in the SHIELD authentication engine.", + "type": "object", + "properties": { + "token": { + "description": "This is transmitted as a property instead of a raw string as the body parser ignores it in Express.JS. Functionally identical though.", + "type": "string", "examples": [ - "271ab834-7469-4f2d-a705-549972c4f325" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1jN2wzSXo5M2c3dXdnTmVFbW13X1dZR1BrbyJ9.eyJhdWQiOiI0YzQwMjgxYi1hMzA1LTRhYWYtOTBhNC1kNWJiZWU2ZWI4ZWQiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vMmQxMDJkYTktZDExZS00YTgwLTkwMjItYzQxOGZhNDg1NGM3L3YyLjAiLCJpYXQiOjE3MjczNzUzNzMsIm5iZiI6MTcyNzM3NTM3MywiZXhwIjoxNzI3Mzc5MjczLCJhaW8iOiJrMkJnWU9BM1ByL2lTc2loRmYzeU9uVk40UTZOc1dsZnRnWEhoMW5HYm5saWVuS1hRZ2tBIiwiYXpwIjoiNGU4NTkxNDYtZjkzZS00OWYyLTk4NmYtYjcyMjI2ZmNkNWI5IiwiYXpwYWNyIjoiMSIsIm9pZCI6ImUyZGU3NDRkLWFmNWUtNDg0MS1iYjhmLTY5NGRkMjVmZWY0ZCIsInJoIjoiMC5BY29BcVMwUUxSN1JnRXFRSXNRWS1raFV4eHNvUUV3Rm82OUtrS1RWdS01dXVPMzZBQUEuIiwicm9sZXMiOlsiVGVsZW1ldHJ5LlNvcC5SZWFkV3JpdGUiLCJMaWNlbnNlUmVwb3J0LlJlYWRXcml0ZSJdLCJzdWIiOiJlMmRlNzQ0ZC1hZjVlLTQ4NDEtYmI4Zi02OTRkZDI1ZmVmNGQiLCJ0aWQiOiIyZDEwMmRhOS1kMTFlLTRhODAtOTAyMi1jNDE4ZmE0ODU0YzciLCJ1dGkiOiJfTGlHVVlsZktrcTRWaEdPXzNpRkFBIiwidmVyIjoiMi4wIn0.CZMOfyo5Lo1Km8bgWtOw8f30n1AZ5HJQ-StyIPr_P_eEjanzHVSEiRsHweNATW0GQFfLs0lGH43xztFcNNepu7CctyEzoktJ-9De2mMLIMJviF1rlB19mxH3a3hUSPZuPeYPPONkYtjL4fZj0mCYcALoq-orc0Oswg0l3fatbS7a-DAgxZdLHa6M7OtXksMlMXwooxmocOQeg_zhpko1zyuzSsVwNrz1uMZYpivwaM1ImWZiqgjMc1NWCN2Co1nYNuvxg6Chcr0OOsPRaXayfzrP7IlsZIg5Itg9lrqN0cjT3t8GSejL2P8HmfPcYftlqOobCesjSfBthir5hGUoNA" + ] + } + }, + "examples": [ + { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1jN2wzSXo5M2c3dXdnTmVFbW13X1dZR1BrbyJ9.eyJhdWQiOiI0YzQwMjgxYi1hMzA1LTRhYWYtOTBhNC1kNWJiZWU2ZWI4ZWQiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vMmQxMDJkYTktZDExZS00YTgwLTkwMjItYzQxOGZhNDg1NGM3L3YyLjAiLCJpYXQiOjE3MjczNzUzNzMsIm5iZiI6MTcyNzM3NTM3MywiZXhwIjoxNzI3Mzc5MjczLCJhaW8iOiJrMkJnWU9BM1ByL2lTc2loRmYzeU9uVk40UTZOc1dsZnRnWEhoMW5HYm5saWVuS1hRZ2tBIiwiYXpwIjoiNGU4NTkxNDYtZjkzZS00OWYyLTk4NmYtYjcyMjI2ZmNkNWI5IiwiYXpwYWNyIjoiMSIsIm9pZCI6ImUyZGU3NDRkLWFmNWUtNDg0MS1iYjhmLTY5NGRkMjVmZWY0ZCIsInJoIjoiMC5BY29BcVMwUUxSN1JnRXFRSXNRWS1raFV4eHNvUUV3Rm82OUtrS1RWdS01dXVPMzZBQUEuIiwicm9sZXMiOlsiVGVsZW1ldHJ5LlNvcC5SZWFkV3JpdGUiLCJMaWNlbnNlUmVwb3J0LlJlYWRXcml0ZSJdLCJzdWIiOiJlMmRlNzQ0ZC1hZjVlLTQ4NDEtYmI4Zi02OTRkZDI1ZmVmNGQiLCJ0aWQiOiIyZDEwMmRhOS1kMTFlLTRhODAtOTAyMi1jNDE4ZmE0ODU0YzciLCJ1dGkiOiJfTGlHVVlsZktrcTRWaEdPXzNpRkFBIiwidmVyIjoiMi4wIn0.CZMOfyo5Lo1Km8bgWtOw8f30n1AZ5HJQ-StyIPr_P_eEjanzHVSEiRsHweNATW0GQFfLs0lGH43xztFcNNepu7CctyEzoktJ-9De2mMLIMJviF1rlB19mxH3a3hUSPZuPeYPPONkYtjL4fZj0mCYcALoq-orc0Oswg0l3fatbS7a-DAgxZdLHa6M7OtXksMlMXwooxmocOQeg_zhpko1zyuzSsVwNrz1uMZYpivwaM1ImWZiqgjMc1NWCN2Co1nYNuvxg6Chcr0OOsPRaXayfzrP7IlsZIg5Itg9lrqN0cjT3t8GSejL2P8HmfPcYftlqOobCesjSfBthir5hGUoNA" + } + ] + }, + "examples": { + "Valid request body": { + "value": { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1jN2wzSXo5M2c3dXdnTmVFbW13X1dZR1BrbyJ9.eyJhdWQiOiI0YzQwMjgxYi1hMzA1LTRhYWYtOTBhNC1kNWJiZWU2ZWI4ZWQiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vMmQxMDJkYTktZDExZS00YTgwLTkwMjItYzQxOGZhNDg1NGM3L3YyLjAiLCJpYXQiOjE3MjczNzUzNzMsIm5iZiI6MTcyNzM3NTM3MywiZXhwIjoxNzI3Mzc5MjczLCJhaW8iOiJrMkJnWU9BM1ByL2lTc2loRmYzeU9uVk40UTZOc1dsZnRnWEhoMW5HYm5saWVuS1hRZ2tBIiwiYXpwIjoiNGU4NTkxNDYtZjkzZS00OWYyLTk4NmYtYjcyMjI2ZmNkNWI5IiwiYXpwYWNyIjoiMSIsIm9pZCI6ImUyZGU3NDRkLWFmNWUtNDg0MS1iYjhmLTY5NGRkMjVmZWY0ZCIsInJoIjoiMC5BY29BcVMwUUxSN1JnRXFRSXNRWS1raFV4eHNvUUV3Rm82OUtrS1RWdS01dXVPMzZBQUEuIiwicm9sZXMiOlsiVGVsZW1ldHJ5LlNvcC5SZWFkV3JpdGUiLCJMaWNlbnNlUmVwb3J0LlJlYWRXcml0ZSJdLCJzdWIiOiJlMmRlNzQ0ZC1hZjVlLTQ4NDEtYmI4Zi02OTRkZDI1ZmVmNGQiLCJ0aWQiOiIyZDEwMmRhOS1kMTFlLTRhODAtOTAyMi1jNDE4ZmE0ODU0YzciLCJ1dGkiOiJfTGlHVVlsZktrcTRWaEdPXzNpRkFBIiwidmVyIjoiMi4wIn0.CZMOfyo5Lo1Km8bgWtOw8f30n1AZ5HJQ-StyIPr_P_eEjanzHVSEiRsHweNATW0GQFfLs0lGH43xztFcNNepu7CctyEzoktJ-9De2mMLIMJviF1rlB19mxH3a3hUSPZuPeYPPONkYtjL4fZj0mCYcALoq-orc0Oswg0l3fatbS7a-DAgxZdLHa6M7OtXksMlMXwooxmocOQeg_zhpko1zyuzSsVwNrz1uMZYpivwaM1ImWZiqgjMc1NWCN2Co1nYNuvxg6Chcr0OOsPRaXayfzrP7IlsZIg5Itg9lrqN0cjT3t8GSejL2P8HmfPcYftlqOobCesjSfBthir5hGUoNA" + }, + "summary": "Example request body", + "description": "An example object that represents the request body to be sent to the API endpoint." + } + } + } + } + }, + "responses": { + "204": { + "description": "Credential was successfully stored" + }, + "400": { + "description": "Invalid Access Token" + } + }, + "tags": ["Authentication"] + } + }, + "/Api/Update": { + "get": { + "summary": "Check if an Update Is Pending", + "description": "Provides the state of the update engine. Where `true` means there is an update detected and `false` means there isn't an update available. This endpoint is available to all authorization levels.", + "operationId": "/Api/Update/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "boolean", + "examples": [true] }, "examples": { - "valid offering ID": { - "value": "271ab834-7469-4f2d-a705-549972c4f325", - "summary": "Example of an offering ID", - "description": "An example of an valid marketplace offering ID in type UUID." - } + "Example value": { + "summary": "Example value", + "description": "An example boolean value that represents an update to SHIELD is pending.", + "value": true + } } + } }, - "search": { - "description": "Used in object filtering.", - "in": "query", - "name": "search", + "description": "OK" + } + }, + "tags": ["Update"] + } + }, + "/Api/Update/Check": { + "get": { + "summary": "Check for a New Version", + "description": "Checks with data gateway and compares the reported version to the version that is locally installed. If there is a difference, a new update is marked as available. Always returns the latest version available on data gateway, even if that version is installed locally.\n\nThis endpoint requires the `Update.Read`, `Update.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Update/Check/Get", + "responses": { + "200": { + "content": { + "application/json": { "schema": { - "examples": [ - "finance" - ], - "type": "string" + "properties": { + "appVersion": { + "description": "Follows symantec versioning as laid out here: https://semver.org/. This number is the version of the application package.", + "examples": ["1.2.3"], + "type": "string" + } + }, + "type": "object", + "examples": [ + { + "appVersion": "1.2.3" + } + ] }, "examples": { - "valid search term": { - "value": "finance", - "summary": "Example search term", - "description": "An example valid search term used in object filtering in a query." + "Example response": { + "summary": "Example reported SHIELD version", + "description": "An example of latest semantic version of the SHIELD available.", + "value": { + "appVersion": "1.2.3" } + } } + } }, - "securityClass": { - "description": "The security class of managed object to retrieve. Unknown values, will be ignored. Please see https://learn.microsoft.com/en-us/security/compass/privileged-access-security-levels for a description of security levels.", - "in": "path", - "name": "securityClass", - "required": true, + "description": "OK" + } + }, + "tags": ["Update"] + } + }, + "/Api/Update/Check/Channel/{Update Channel Name}": { + "get": { + "summary": "Check for a New Version in Channel", + "description": "Checks with the SHI Data Gateway in the specified update channel and compares the reported version to the version that is locally installed. If there is a difference, a new update is marked as available. Always returns the latest version available on data gateway, even if that version is installed locally.\n\nThis endpoint requires the `Update.Read`, `Update.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Update/Check/Channel/UpdateChannelName/Get", + "parameters": [ + { + "$ref": "#/components/parameters/updateChannelName" + } + ], + "responses": { + "200": { + "content": { + "application/json": { "schema": { - "$ref": "#/components/schemas/SecurityClassList" + "properties": { + "appVersion": { + "description": "Follows symantec versioning as laid out here: https://semver.org/. This number is the version of the application package.", + "examples": ["1.2.3"], + "type": "string" + } + }, + "type": "object", + "examples": [ + { + "appVersion": "1.2.3" + } + ] }, "examples": { - "Privileged": { - "value": "Privileged", - "summary": "Example security class", - "description": "An example enum string that indicates the security class of an managed object is privileged." + "SHIELD version": { + "summary": "Example semantic version", + "description": "An example string that represents the latest semantic version of SHIELD available in specific channel.", + "value": { + "appVersion": "1.2.3" } + } } + } }, "templateId": { "description": "Reference to the specific configuration item that is deployed in the tenant.", @@ -181,471 +1946,895 @@ "name": "Update Channel Name", "required": true, "schema": { - "examples": [ - "stable" - ], - "type": "string", - "enum": [ - "alpha", - "beta", - "stable" - ] + "$ref": "#/components/schemas/Discover.ExecutionStatus" }, "examples": { - "valid channel name": { - "value": "stable", - "summary": "Example of an update channel name", - "description": "An example of an valid update channel name that should be used when querying or downloading updates." - } + "Execution Status": { + "value": { + "running": true + }, + "summary": "Example execution status", + "description": "An example execution status object that indicates a SHIELD Discover run is already in progress." + } } + } }, - "userId": { - "description": "The SHIELD ID (Entra ID User's Object ID) of the managed user to target.", - "in": "path", - "name": "userId", - "required": true, + "description": "OK" + } + }, + "tags": ["Discover"] + } + }, + "/Api/Discover/Progress": { + "get": { + "summary": "Current execution progress of the Discover module.", + "description": "Provides a detailed breakdown of the current progress of the discover module and it progress.\n\nThis endpoint requires the `Discover.Read`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Discover/Progress/Get", + "responses": { + "200": { + "content": { + "application/json": { "schema": { - "examples": [ - "264a8bed-0714-48fd-8b9d-0e4c4715cee5" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "$ref": "#/components/schemas/Core.ProgressBar" }, "examples": { - "valid user ID": { - "value": "264a8bed-0714-48fd-8b9d-0e4c4715cee5", - "summary": "Example of a user ID", - "description": "An example of valid EntraID managed user ID in type UUID." - } + "Progress Bar": { + "value": { + "childBar": [], + "description": "Collecting data from the Microsoft Entra ID system.", + "displayName": "Running Entra ID Plugin", + "id": "b759230f-48cb-496e-ad57-5f079083226b", + "currentStep": 5, + "totalStepCount": 7 + }, + "summary": "Example progress bar object", + "description": "An example progress bar object returned from the endpoint. It indicates:
- The purpose of a progress bar.
- The text label of a progress bar.
- The unique identifier in type UUID of a specific SHIELD instance for search.
- The total number of steps of a progress bar.
- The current step/value of a progress bar.
- No child progress bar." + } } - } + } + }, + "description": "OK" + } }, + "tags": ["Discover"] + } + }, + "/Api/Discover/Report": { + "get": { + "summary": "Start Discover's Report Generation", + "description": "Starts the Discover module's report collection engine to create a license report and upload it to the data gateway.\n\nThis endpoint requires the `Discover.Action.Run`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Discover/Report/Start", "responses": { - "201": { - "description": "The authorization was recorded successfully." - }, - "202": { - "description": "The process to create a report has started." - }, - "400": { - "description": "Invalid input!" - }, - "401": { - "description": "Principal is not authorized to access this endpoint. Check to make sure the Bearer token is valid and present!" - }, - "403": { - "description": "Principal does not contain the correct scopes (permissions) for the API call that was made, or was made from the wrong tenant. If the permissions were granted, ensure that the access token was requested with the correct scopes." - }, - "404": { - "description": "The requested object was not found." - }, - "409": { - "description": "A job is already in progress." - }, - "525": { - "description": "Infrastructure not deployed. Please deploy the infrastructure before using this endpoint." - } + "202": { + "$ref": "#/components/responses/202" + }, + "409": { + "$ref": "#/components/responses/409" + } }, - "schemas": { - "Core.SystemRequirements": { - "title": "Core - System Requirements", - "description": "Collection of indicators that notify the caller if the system requirements have been met for various sub components to operate.", - "properties": { - "authenticatorPermissions": { - "description": "Flag that indicates if the core permissions for the SHIELD - Authenticator App have been configured properly or not.", - "type": "boolean", - "examples": [ - true - ] - }, - "azurePermissions": { - "description": "Flag that indicates if the required core Azure RBAC assignment(s) are present or not.", - "type": "boolean", - "examples": [ - false - ] - }, - "defendEntitlement": { - "description": "Flag that indicates if the required defend licenses are present or not.", - "type": "boolean", - "examples": [ - true - ] - }, - "deployEntitlement": { - "description": "Flag that indicates if the required deploy licenses are present or not.", - "type": "boolean", - "examples": [ - true - ] - }, - "discoverEntitlement": { - "description": "Flag that indicates if the required discover licenses are present or not.", - "type": "boolean", - "examples": [ - true - ] - }, - "msGraphPermissions": { - "description": "Flag that indicates if the core permissions for the Microsoft Graph API have been configured properly or not.", - "type": "boolean", - "examples": [ - false - ] - }, - "dataGatewayPermissions": { - "description": "Flag that indicates if the core permissions for the SHI - Data Gateway have been configured properly or not.", - "type": "boolean", - "examples": [ - false - ] - }, - "entraDirectoryRole": { - "description": "Flag that indicates if the core permissions for Entra Directory Role assignment have been configured properly or not.", - "type": "boolean", - "examples": [ - false - ] + "tags": ["Discover"] + } + }, + "/Api/Discover/LicenseReport/Correlation": { + "get": { + "description": "Retrieves the list of correlation records for the authenticated tenant. Correlation records store the metadata for a specific license report.\n\nThis endpoint requires the `Discover.Read`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Discover/LicenseReport/Correlation/Get", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "anything": { + "description": "Sample list of correlation records for the authenticated tenant.", + "summary": "Available Correlation Records", + "value": [ + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-08-01T21:14:45.026Z", + "updatedAt": "2024-08-01T21:14:45.026Z" + }, + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-07-25T21:14:45.026Z", + "updatedAt": "2024-07-25T21:14:45.026Z" + } + ] + } + }, + "schema": { + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + }, + "examples": [ + [ + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-08-01T21:14:45.026Z", + "updatedAt": "2024-08-01T21:14:45.026Z" + }, + { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", + "createdAt": "2024-07-25T21:14:45.026Z", + "updatedAt": "2024-07-25T21:14:45.026Z" + } + ] + ] + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["Discover"], + "summary": "Retrieve the List of Correlation Records" + } + }, + "/Api/Discover/LicenseReport/Correlation/{correlationId}/Data": { + "get": { + "description": "Retrieves the full license report for the specified correlation ID in the authenticated tenant. The license report contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `Discover.Read`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Discover/LicenseReport/Correlation/:correlationId/Data/Get", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "License Report": { + "description": "Sample, truncated report from an example customer environment.", + "summary": "Example License Report", + "value": { + "availableLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, + "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, + "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, + "d76878d6-1495-4243-a334-a82bb9818cd0": 500 + }, + "correlation": { + "auditTenantAccount": "somebodyThatI@example.com", + "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", + "reportTenantAccount": "usedToKnow@example.com", + "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, + "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { + "Something Here": true, + "Other Obscure feature": false + } + } + }, + "04e88835-771a-482b-9d6f-ba06c32cbb67": { + "assignedLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, + "consumedService": { + "9d3603de-b378-4c4a-adcc-ee133cbef914": null, + "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { + "Something Here": true, + "Other Obscure feature": false + } + } + } + } } + } + }, + "schema": { + "$ref": "#/components/schemas/LicenseReport" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "tags": ["Discover"], + "summary": "Retrieve the Specified License Report" + } + }, + "/Api/Deploy": { + "get": { + "description": "Has the core infrastructure engine check if the config engine can initialize properly.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Get", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Infra deployed": { + "description": "All API calls should be available since the core infrastructure is deployed.", + "summary": "Infrastructure is deployed", + "value": true + }, + "Infra not deployed": { + "description": "Infrastructure is not deployed. Please run the deployment before attempting different API calls.", + "summary": "Infrastructure is not deployed", + "value": false + } + }, + "schema": { + "type": "boolean", + "examples": [true] + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + } + }, + "summary": "Get the current status of the infrastructure deployment", + "tags": ["Infrastructure Deployment"] + }, + "post": { + "description": "After the user consents, deploy the core security groups, scope tag, configurations and metadata.\n\nThis endpoint requires the `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Post", + "requestBody": { + "content": { + "application/json": { + "examples": { + "Ignorant Deploy Request": { + "description": "Clueless dev trying to automate this application without reading the docs. RTFM!", + "summary": "Ignorant Deploy Request", + "value": {} + }, + "No User Consent": { + "description": "User did not agree to the terms and conditions. This post should not have been sent.", + "summary": "User Did Not Consent", + "value": { + "deploymentConsent": false + } + }, + "User Consented": { + "description": "User agreed to the terms and conditions and pressed the deploy button.", + "summary": "User Consented", + "value": { + "deploymentConsent": true + } + } + }, + "schema": { + "properties": { + "deploymentConsent": { + "type": "boolean", + "examples": [true] + } }, "type": "object", - "required": [ - "authenticatorPermissions", - "azurePermissions", - "defendEntitlement", - "deployEntitlement", - "discoverEntitlement", - "msGraphPermissions", - "dataGatewayPermissions", - "entraDirectoryRole" - ], "examples": [ + { + "deploymentConsent": true + } + ] + } + } + } + }, + "responses": { + "204": { + "content": { + "application/json": { + "examples": { + "Successful Deployment": { + "description": "When a deployment request is successfully executed, a boolean true is returned.", + "summary": "Successful Deployment", + "value": true + } + }, + "schema": { + "type": "boolean", + "examples": [true] + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + } + }, + "summary": "Deploy the core infrastructure architecture specification", + "tags": ["Infrastructure Deployment"], + "security": [] + } + }, + "/Api/Deploy/Progress": { + "get": { + "summary": "Current execution progress of the Deploy module.", + "description": "Provides a detailed breakdown of the current progress of the deploy module and its sub-components, if any.\n\nThis endpoint requires the `Deploy.Read`, or the `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Progress/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Core.ProgressBar" + }, + "examples": { + "Progress Bar": { + "value": { + "childBar": [ + { + "description": "Collecting data from the Microsoft Purview.", + "displayName": "Running SHIELD Deploy - Purview", + "id": "b759230f-48cb-496e-ad57-5f079083226c", + "currentStep": 1, + "totalStepCount": 3 + } + ], + "description": "Collecting data from the Microsoft Entra ID system.", + "displayName": "Running SHIELD Deploy", + "id": "b759230f-48cb-496e-ad57-5f079083226b", + "currentStep": 5, + "totalStepCount": 7 + }, + "summary": "Example progress bar object", + "description": "An example progress bar object returned from the endpoint. It indicates:
- The purpose of a progress bar.
- The text label of a progress bar.
- The unique identifier in type UUID of a specific SHIELD instance for search.
- The total number of steps of a progress bar.
- The current step/value of a progress bar.
- With a child progress bar." + } + } + } + }, + "description": "OK" + } + }, + "tags": ["Infrastructure Deployment"] + } + }, + "/Api/Deploy/Version": { + "get": { + "description": "Gets the version of the API server and the architecture version deployed as well as the supported version of the architecture spec from the server.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Version/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "apiVersion": { + "description": "Follows symantec versioning as laid out here: https://semver.org/. This number is the version of the API server.", + "examples": ["1.2.3"], + "type": "string" + }, + "archSpecVersion": { + "description": "An incrementing number that describes the version of the architecture specification that the API supports.", + "examples": ["25"], + "type": "string", + "minLength": 1 + }, + "deployedArchVersion": { + "description": "The version of the architecture specification that is currently deployed.", + "examples": ["23"], + "type": "string", + "minLength": 1 + } + }, + "type": "object", + "examples": [ { - "authenticatorPermissions": true, - "azurePermissions": false, - "defendEntitlement": true, - "deployEntitlement": false, - "discoverEntitlement": true, - "msGraphPermissions": false, - "dataGatewayPermissions": false, - "entraDirectoryRole": false + "apiVersion": "1.2.3", + "archSpecVersion": "25", + "deployedArchVersion": "23" } - ] + ] + }, + "examples": { + "Versions response": { + "summary": "Example versions response", + "description": "An example object that represents the aggregation of versioning information of all SHIELDs components. including:
- Semantic version of the API server.
- The incrementing architecture specification version that the API supports.
- The incrementing architecture specification version that is currently deployed.", + "value": { + "apiVersion": "1.2.3", + "archSpecVersion": "25", + "deployedArchVersion": "23" + } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + } + }, + "summary": "Gets the version of SHIELDs components", + "tags": ["Infrastructure Deployment"] + } + }, + "/Api/Defend/Intermediary/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { + "get": { + "description": "Retrieves a list of all AVD intermediaries for the specified security class filter. Next links may be provided for pagination to allow for good performance on larger environments. If a nextLink is return, not all data was returned on this query and the next link can be sent back to the API to get the next page of data.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/Type/:securityClass/Offering/AVD/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/nextLink" + }, + { + "$ref": "#/components/parameters/search" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" + }, + "examples": { + "Paged AVD intermediaries": { + "summary": "Example paged AVD intermediary list", + "description": "An example paged AVD intermediary list returned that represents the current page of all AVD intermediary instances form the specified security class.", + "value": { + "@odata.count": 1, + "@odata.nextLink": "1", + "value": [ + { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged", + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + ] + } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Retrieves all AVD Intermediary Instances", + "tags": ["Intermediary"] + } + }, + "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { + "delete": { + "description": "Deletes the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + } + ], + "responses": { + "204": { + "description": "OK: Deleted successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Deletes a Single AVD Intermediary Instance", + "tags": ["Intermediary"] + }, + "get": { + "description": "Retrieves the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" + }, + "examples": { + "Paged AVD intermediary result": { + "summary": "Example paged result of a AVD intermediary list", + "description": "An example paged result that represents the current page of retrieved AVD intermediary list from a parent group filtered by specified class.", + "value": { + "@odata.count": 1, + "@odata.nextLink": "1", + "value": [ + { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged", + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + ] + } + } + } + } }, - "Core.ProgressBar": { - "title": "Core - Progress Bar", - "description": "Used to indicate the progress of a long running operation.", + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Retrieves a Single AVD Intermediary Instance", + "tags": ["Intermediary"] + } + }, + "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign": { + "delete": { + "description": "Removes the specified user(s) as identified by their Object ID from the AVD cluster and deletes their corresponding session host(s).\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "One user": { + "description": "Removes 1 session host, and removed the requested user from the assignments security group.", + "summary": "Remove Single User", + "value": { + "userList": ["cf5b12a9-b939-4d5c-a380-fb62e4fe88ef"] + } + }, + "Two users": { + "description": "Removes 3 session hosts, and removed the requested users from the assignments security group.", + "summary": "Remove Multiple Users", + "value": { + "userList": [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc", + "dd27937c-6287-45b3-98de-387725b068f3", + "989d3dc1-43f4-4ff7-82ba-43661f94a428" + ] + } + } + }, + "schema": { "properties": { - "childBar": { - "description": "Sub progress bar that should appear below the current progress bar for a dependent execution branch.", - "type": "array", - "minItems": 0, - "items": { - "$ref": "#/components/schemas/Core.ProgressBar" + "userList": { + "items": { + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + } + } + }, + "responses": { + "204": { + "description": "OK: Deleted successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Removes the assignment of the specified users", + "tags": ["Intermediary"] + }, + "get": { + "description": "Gets the list of assigned user from the specified AVD Intermediary.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + }, + { + "$ref": "#/components/parameters/nextLink" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObjectPage.ManagedUser" + }, + "examples": { + "Managed user page": { + "summary": "Example paged user result", + "description": "An example of paged user result that represents the current page of assigned user list retrieved from the specified AVD intermediary.", + "value": { + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] }, + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "deviceAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", + "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", + "temporaryAccessPass": "BCKTSN#E2R&5" + } + ] + } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "List all assigned users (paginated)", + "tags": ["Intermediary"] + }, + "post": { + "description": "Assigns the specified user(s) as identified by their Object ID to the AVD cluster and create corresponding session host(s) for them.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Post", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "One user": { + "description": "Creates 1 session host, and added the requested user to the assignments security group.", + "summary": "Assign Single User", + "value": { + "userList": ["cf5b12a9-b939-4d5c-a380-fb62e4fe88ef"] + } + }, + "Two users": { + "description": "Creates 3 session hosts, and added the requested users to the assignments security group.", + "summary": "Assign Multiple Users", + "value": { + "userList": [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc", + "dd27937c-6287-45b3-98de-387725b068f3", + "989d3dc1-43f4-4ff7-82ba-43661f94a428" + ] + } + } + }, + "schema": { + "properties": { + "userList": { + "items": { + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string", + "examples": ["0c56b055-9042-4f54-8e6e-6510e12a81dc"] + }, + "type": "array", + "examples": [["0c56b055-9042-4f54-8e6e-6510e12a81dc"]] + } + }, + "type": "object", + "examples": [ + { + "userList": ["0c56b055-9042-4f54-8e6e-6510e12a81dc"] + } + ] + }, + "Deploy.ConfigurationTag": { + "title": "Deploy - Configuration Tag", + "description": "Definition of an object representing configuration tag used within architecture collections.", + "type": "object", + "properties": { + "advanced": { + "type": "boolean", + "description": "Flag indicating if additional challenges should be required before user can use this configuration item.", "examples": [ - [ - { - "description": "Collecting data from the Microsoft Entra ID system.", - "displayName": "Running Entra ID Plugin", - "id": "b759230f-48cb-496e-ad57-5f079083226b", - "currentStep": 5, - "totalStepCount": 7 - } - ] + false ] }, "description": { "type": "string", - "description": "Long form text describing the current step.", + "description": "Long form explanation what the tag is and/or does.", "examples": [ - "Collecting data from the Microsoft Entra ID system." + "This tag indicates specific collection and very important." ] }, "displayName": { "type": "string", - "description": "Text/label to render with the progress bar.", + "description": "Human friendly name of the config tag.", + "examples": [ + "Important Collection" + ] + }, + "dependentTag": { + "type": "array", + "description": "List of configuration tags that are required to be selected if this one were to be selected. This property is primarily used for illustration to the end user or system.", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/Deploy.ConfigurationTag" + }, "examples": [ - "Running Entra ID Plugin" + [ + { + "advanced": false, + "description": "This tag indicates specific collection and very important.", + "displayName": "Important Collection", + "dependentTag": [], + "id": "2c7e1a3b-5d4f-4a8b-9e6a-1c2b7f3d8e4a" + } + ] ] }, "id": { - "description": "Unique identifier to be able to select this specific instance via search.", "type": "string", + "description": "Object ID of the config tag entity.", "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "examples": [ - "b759230f-48cb-496e-ad57-5f079083226b" + "8b3e2a1c-7d4f-4a8b-9e6a-2c1b7f3d8e4a" ] - }, - "currentStep": { - "description": "Current step/value for the progress bar. This is in relation to the `totalStepCount` property. If undefined, an indeterminate/pulsing progress bar is used instead.", - "examples": [ - 5 - ], - "type": "number" - }, - "totalStepCount": { - "description": "Number of steps before the progress bar is completely filed.", - "examples": [ - 7 - ], - "type": "number", - "minimum": 1 } }, - "type": "object", "required": [ - "childBar", + "advanced", + "description", "displayName", - "id", - "totalStepCount" + "dependentTag", + "id" ], "examples": [ { - "childBar": [], - "description": "Collecting data from the Microsoft Entra ID system.", - "displayName": "Running Entra ID Plugin", - "id": "b759230f-48cb-496e-ad57-5f079083226b", - "currentStep": 5, - "totalStepCount": 7 - } - ] - }, - "Authenticator.RequestStatus": { - "title": "Authentication - Status", - "description": "List of credentials that are being waited for by SHIELD's internal authentication engine.", - "properties": { - "accessToken": { - "oneOf": [ - { - "description": "Flag that represents if the server is not waiting for a specific access token.", - "type": "boolean", - "examples": [ - false - ] - }, - { - "$ref": "#/components/schemas/Authenticator.Status.TokenAudience" - } - ], - "examples": [ - false, - { - "audience": "00000002-0000-0000-b000-000000000000" - } - ] - }, - "sccAuth": { - "description": "Flag that represents if the server is waiting for SCC Auth credentials.", - "type": "boolean", - "examples": [ - true - ] - } - }, - "type": "object", - "required": [ - "accessToken", - "sccAuth" - ], - "examples": [ - { - "accessToken": { - "audience": "00000002-0000-0000-b000-000000000000" - }, - "sccAuth": true - } - ] - }, - "Authenticator.Status.TokenAudience": { - "title": "SHIELD - Authenticator - Status - Token Audience", - "description": "If a access token is being requested, this is the audience that the access token should have when being submitted.", - "properties": { - "audience": { - "description": "Audience ID of the access token that is being requested.", - "type": "string", - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "examples": [ - "00000002-0000-0000-b000-000000000000" - ] - } - }, - "type": "object", - "required": [ - "audience" - ], - "examples": [ - { - "audience": "00000002-0000-0000-b000-000000000000" - } - ] - }, - "Authenticator.Container.SccAuthCredentials": { - "title": "SHIELD - Authenticator - SCC Auth", - "description": "SHIELD - Defender, and Purview portal Container Credentials", - "type": "object", - "properties": { - "authenticatedUpn": { - "description": "User principal name of the user that authenticated to the portals.", - "examples": [ - "user@example.com" - ], - "type": "string", - "format": "email" - }, - "expiration": { - "description": "Point in time at which the whole authentication structure has an expired state and is un-useable.", - "examples": [ - "2024-09-26T18:16:29.340Z" - ], - "type": "string", - "format": "date-time" - }, - "defender": { - "$ref": "#/components/schemas/Authenticator.Container.SccAuthCredentials.CredentialContainer" - }, - "security": { - "$ref": "#/components/schemas/Authenticator.Container.SccAuthCredentials.CredentialContainer" - }, - "purview": { - "$ref": "#/components/schemas/Authenticator.Container.SccAuthCredentials.CredentialContainer" - } - }, - "required": [ - "authenticatedUpn", - "security", - "purview" - ], - "examples": [ - { - "authenticatedUpn": "user@example.com", - "security": { - "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", - "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" - }, - "purview": { - "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", - "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" - }, - "expiration": "2024-09-26T18:16:29.340Z", - "defender": { - "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", - "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" - } - } - ] - }, - "Authenticator.Container.SccAuthCredentials.CredentialContainer": { - "title": "SHIELD - Authenticator - SCC Auth - Credential Container", - "description": "Container for the credentials for a single SccAuth authenticated site.", - "properties": { - "sccAuth": { - "description": "Authentication token.", - "examples": [ - "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)" - ], - "type": "string" - }, - "xsrf": { - "description": "Cross Site Request Forgery Prevention Token.", - "examples": [ - "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" - ], - "type": "string" - } - }, - "required": [ - "sccAuth", - "xsrf" - ], - "type": "object", - "examples": [ - { - "sccAuth": "54BKPtTL-eSMFp5cqYTMMSblm2U80cUJqQgmbe4f_sRn4ammMmU1NKNurn9HqpsUtS4FrMJRTKa3Or_pFbedM_57R0fVBfNJ-m2Pvey9OweWIDradzT0dB1WnufPTJiT2y7zSQy91Y9wJIn1_aY5q-MNh75qwjM84Dng-mYzbd9KqUfyPUolOo-j-... (Truncated)", - "xsrf": "PEDwTvWdm2qSTe-n8h-1praK4OcQK1ELTJ08DWYqBRzQiyA2MIuEKEMNLu4ExjDNpAOUnAxmsqOeuGzb82MJYkegOE6hW8BzpSM6k9nbTbJ4yjNGzMSQvWUnyqrBvGa8JfSRiSeaKdXGBnxGd90Spw2:... (truncated)" - } - ] - }, - "Deploy.ConfigurationTag": { - "title": "Deploy - Configuration Tag", - "description": "Definition of an object representing configuration tag used within architecture collections.", - "type": "object", - "properties": { - "advanced": { - "type": "boolean", - "description": "Flag indicating if additional challenges should be required before user can use this configuration item.", - "examples": [ - false - ] - }, - "description": { - "type": "string", - "description": "Long form explanation what the tag is and/or does.", - "examples": [ - "This tag indicates specific collection and very important." - ] - }, - "displayName": { - "type": "string", - "description": "Human friendly name of the config tag.", - "examples": [ - "Important Collection" - ] - }, - "dependentTag": { - "type": "array", - "description": "List of configuration tags that are required to be selected if this one were to be selected. This property is primarily used for illustration to the end user or system.", - "minItems": 0, - "items": { - "$ref": "#/components/schemas/Deploy.ConfigurationTag" - }, - "examples": [ - [ - { - "advanced": false, - "description": "This tag indicates specific collection and very important.", - "displayName": "Important Collection", - "dependentTag": [], - "id": "2c7e1a3b-5d4f-4a8b-9e6a-1c2b7f3d8e4a" - } - ] - ] - }, - "id": { - "type": "string", - "description": "Object ID of the config tag entity.", - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "examples": [ - "8b3e2a1c-7d4f-4a8b-9e6a-2c1b7f3d8e4a" - ] - } - }, - "required": [ - "advanced", - "description", - "displayName", - "dependentTag", - "id" - ], - "examples": [ - { - "advanced": true, - "description": "This tag indicates optional collection and can be skipped.", - "displayName": "Optional Collection", - "dependentTag": [], - "id": "4d1c7e2b-3a5f-4a8b-9e6a-7f2b3d1c9e45" + "advanced": true, + "description": "This tag indicates optional collection and can be skipped.", + "displayName": "Optional Collection", + "dependentTag": [], + "id": "4d1c7e2b-3a5f-4a8b-9e6a-7f2b3d1c9e45" } ] }, @@ -1666,527 +3855,484 @@ ] } }, - "required": [ - "assignedLicense", - "assignedService", - "consumedService" - ], - "description": "Collection of principals that have had their in-use licenses and assigned licenses. Where the key is the principal ID and the value is the insights.", - "examples": [ - { - "assignedLicense": { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": null, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": null, - "7159f980-6f83-4b67-bf41-e172b3ae1352": null - }, - "assignedService": { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": { - "Conditional Access": false, - "Access Review": true, - "Entitlement Management": false, - "Identity Protection": true - }, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { - "Conditional Access": true, - "Dynamic Group": false, - "Group Naming": true, - "On-Prem SSPR": false, - "Group Expiration": true, - "Provisioning Engine": true, - "Enterprise State Roaming": false - }, - "6511755b-c27d-4c66-a59e-b835e6b54e7f": null + "examples": { + "Example response": { + "summary": "Example paged response", + "description": "An example of ObjectPage.ManagedUser returned that represents the list of users assigned to specific privileged device.", + "value": { + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] }, - "consumedService": { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": { - "Conditional Access": true, - "Access Review": false, - "Entitlement Management": false, - "Identity Protection": true - }, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { - "Conditional Access": true, - "Dynamic Group": false, - "Group Naming": true, - "On-Prem SSPR": false, - "Group Expiration": true, - "Provisioning Engine": true, - "Enterprise State Roaming": false - }, - "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null, - "c90f1a25-e6cd-4163-ac6c-ca7616c585a9": null + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "deviceAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", + "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", + "temporaryAccessPass": "BCKTSN#E2R&5" } + ] } - ], - "title": "License Report - License Data" + } + } + } }, - "LicenseReport.FeatureBreakdown": { - "additionalProperties": { - "type": "boolean", - "examples": [ - true + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "List User Assignments", + "tags": ["Device Management"] + }, + "post": { + "description": "Adds the specified list of users to the list of users that are allowed to log in on the specific privileged device.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Post", + "parameters": [ + { + "$ref": "#/components/parameters/deviceId" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "1:1 map": { + "description": "This example is the security best practice of having only one user mapped to a managed device.", + "summary": "1:1 User Mapping", + "value": { + "userList": ["0674276a-31e8-4773-8ed9-6fb49dbd0fa8"] + } + }, + "Multi-User Managed Device": { + "description": "This example is the security best practice of having multiple users mapped to a managed device.", + "summary": "Multi-User Assignment", + "value": { + "userList": [ + "0674276a-31e8-4773-8ed9-6fb49dbd0fa8", + "66714224-b1a6-4fd6-b9d8-5263fdf755fc" ] + } + } + }, + "schema": { + "properties": { + "userList": { + "items": { + "examples": ["d1bc9d1a-5a30-4d66-898a-1dd300e707bc"], + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "type": "array", + "examples": [["d1bc9d1a-5a30-4d66-898a-1dd300e707bc"]] + } }, - "description": "List of features that are configured for the specific service plan's service configuration for the related principal.\nThe key is the name of the feature that is being described.\nThe value is the state of the feature configuration, `true` is in scope and `false` meaning not in scope.", + "type": "object", "examples": [ - { - "Conditional Access": true, - "Access Reviews": true, - "Dynamic Groups": false, - "On-Prem Password Rest": true, - "On-Prem Password Protection": false - } - ], - "title": "License Report - Feature Breakdown", - "type": "object" + { + "userList": ["d1bc9d1a-5a30-4d66-898a-1dd300e707bc"] + } + ] + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/ManagedObject.User" + }, + "minItems": 0, + "type": "array" + }, + "examples": { + "List of Managed Users": { + "summary": "Users assigned to the privileged device", + "description": "An example of ManagedObject.User array that represents the list of users which successfully assigned to the specified privileged device.", + "value": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + } + ] + } + } + } }, - "LicenseReport": { - "description": "Completely calculated license report structure that is the result of a complete run.", - "examples": [ - { - "availableLicense": { - "e17b13ee-9749-488b-9289-d31a8fde045d": 123, - "2d995b6a-d4aa-4d8d-a03c-372ecb66509d": 456, - "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 789 - }, - "correlation": { - "auditTenantAccount": "admin-user@example.com", - "correlationId": "88da2253-758f-4135-9d37-64448c8b65c1", - "reportTenantAccount": "generic-user@example.com", - "tenantId": "0e1fe83f-a33f-4250-8546-225b8d45ae01" + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Add User Assignments", + "tags": ["Device Management"] + } + }, + "/Api/Defend/Device/Type/{securityClass}": { + "get": { + "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", + "operationId": "/Api/Defend/Device/Type/:securityClass/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/nextLink" + }, + { + "$ref": "#/components/parameters/search" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObjectPage.ManagedDevice" + }, + "examples": { + "Managed device list": { + "summary": "Example list of managed devices", + "description": "An example paged result returned that represents a specific page of managed device list.", + "value": { + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" }, - "licenseData": { - "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { - "assignedLicense": { - "e17b13ee-9749-488b-9289-d31a8fde045d": null - }, - "assignedService": { - "cbf6ee7c-c3c1-44a6-9f18-020c65536470": null, - "c7bcba35-199c-41e5-8c8d-6d4e4aad8964": null - }, - "consumedService": { - "fe98c41a-d931-4f6f-a5bc-750ba7144a77": null, - "0474bdf1-ee76-4aff-a65c-6f82e5e1d5a6": { - "Something Here": true, - "Other Obscure feature": false - } - } - } + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", + "securityClass": "Privileged", + "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "userAssignmentList": [ + "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", + "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", + "c54d4854-9254-4689-8a22-1cc80a3dae4e" + ] } + ] } - ], - "type": "object", + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Get All Devices", + "tags": ["Device Management"] + }, + "post": { + "description": "Commissions a new device, into the device hierarchy and appends appropriate metadata and initial policies. Appends required metadata to proper locations.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Device/Type/:securityClass/Post", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Request body": { + "value": { + "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" + }, + "summary": "Example request body", + "description": "An example request body object that represents a request to commission the device specified in the deviceId field." + } + }, + "schema": { "properties": { - "availableLicense": { - "additionalProperties": { - "examples": [ - 1234 - ], - "type": "integer" - }, - "description": "Breakdown of the purchased licenses/service plans available in the tenant being audited for this run. Where the key is the ID of the service plan and the value is how many licenses are available/purchase for it.", - "examples": [ - { - "eec0eb4f-6444-4f95-aba0-50c24d67f998": 1234, - "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 123 - } - ], - "title": "License Report - Available Licenses", - "type": "object" - }, - "correlation": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" - }, - "licenseData": { - "additionalProperties": { - "$ref": "#/components/schemas/LicenseReport.LicenseData" - } - } + "deviceId": { + "description": "The SHIELD ID (Entra ID Device ID) of the device to target.", + "examples": ["75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + } }, - "required": [ - "availableLicense", - "correlation", - "licenseData" - ], - "title": "License Report - Complete Object" - }, - "ManagedObject.Device": { - "title": "Managed Device", - "description": "Structure that represents a all of the states a managed device could be in.", + "required": ["deviceId"], "type": "object", "examples": [ - { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "securityClass": "Privileged", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" - } - ], - "properties": { - "commissionedDate": { - "description": "This is the ISO 8601 string format of the time representing the commission date of the PAW.", - "examples": [ - "2023-02-04T05:06:09.601Z" - ], - "format": "date-time", - "type": "string" - }, - "displayName": { - "description": "Current computer name of the device according to Entra ID. Empty string indicates that the device has not joined Entra ID yet.", - "examples": [ - "Priv-01534962354" - ], - "maxLength": 15, - "minLength": 0, - "type": "string" - }, - "id": { - "description": "Entra ID Device ID (Not Object ID) of the specified device.", - "examples": [ - "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" - }, - "parentDeviceId": { - "description": "DeviceID of the parent PAW device.", - "examples": [ - "81682cf5-0405-491d-8ab8-e07c778d7eaf" - ], - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "securityClass": { - "$ref": "#/components/schemas/SecurityClassList" - }, - "uniqueGroupId": { - "description": "The object ID of the unique security group that contains the managed Entra ID Device Identity.", - "examples": [ - "146964e0-8ca4-4af0-9c2a-894b32912463" - ], - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" - } - }, - "required": [ - "commissionedDate", - "displayName", - "id", - "securityClass", - "uniqueGroupId" + { + "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" + } ] + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.Device" + }, + "examples": { + "Commissioned managed device": { + "summary": "Example managed device info", + "description": "An example managed device object returned that represents a successfully commissioned device.", + "value": { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + } + } + } + } }, - "ManagedObject.PrivilegedDevice": { - "description": "Set of properties that are available on privileged managed device objects only.", - "title": "Managed Device - Privileged", - "type": "object", - "allOf": [ - { - "$ref": "#/components/schemas/ManagedObject.Device" - }, - { - "type": "object", - "properties": { - "groupAssignmentId": { - "description": "This is the ID of the Custom CSP Device Configuration that configures the local admin and local hyper-v group memberships.", - "examples": [ - "830d8b6f-2f6f-41f7-8800-0c07445abd36" - ], - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "securityClass": { - "$ref": "#/components/schemas/SecurityClassList" - }, - "userAssignmentId": { - "description": "The ID of the Settings Catalog that contains the user rights assignment of the specified PAW device.", - "examples": [ - "146964e0-8ca4-4af0-9c2a-894b32912463" - ], - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" - }, - "userAssignmentList": { - "description": "List of Object IDs for the privileged user accounts that are assigned to this device.", - "examples": [ - [ - "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", - "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", - "c54d4854-9254-4689-8a22-1cc80a3dae4e" - ] - ], - "type": "array", - "items": { - "type": "string", - "format": "uuid" - } - } - }, - "required": [ - "groupAssignmentId", - "securityClass", - "userAssignmentId", - "userAssignmentList" - ], - "examples": [ - { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", - "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", - "securityClass": "Privileged", - "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", - "userAssignmentList": [ - "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", - "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", - "c54d4854-9254-4689-8a22-1cc80a3dae4e" - ] - } - ] - } - ] + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Commission a New Device", + "tags": ["Device Management"] + } + }, + "/Api/Defend/Device/{deviceId}/Type/{securityClass}": { + "delete": { + "description": "Removes the device from the management hierarchy, removes metadata tagging and issues the wipe command to the devices.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/deviceId" + } + ], + "responses": { + "204": { + "description": "OK: Deleted successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Decommission Specified Device", + "tags": ["Device Management"] + }, + "get": { + "description": "Get the specified managed device by its Entra ID Device ID.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/deviceId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.Device" + }, + "examples": { + "Managed device": { + "summary": "Example managed device", + "description": "An example of ManagedObject.Device object returned that represents a managed device queried by a device ID with specified security class.", + "value": { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + } + } + } + } }, - "ManagedObject.User": { - "title": "Managed User", - "description": "A user object that has limited properties. The user object is generated by combining multiple pieces of metadata from Entra ID and SHIELD.", - "properties": { - "creationDate": { - "description": "A date object representing when the user managed by SHIELD.", - "examples": [ - "2023-10-21T15:24:47.970Z" - ], - "format": "date-time", - "readOnly": true, - "type": "string" - }, - "displayName": { - "description": "The name shown on UIs for the privileged user according to Entra ID.", - "examples": [ - "Example User (Priv)" - ], - "maxLength": 256, - "type": "string" - }, - "firstName": { - "description": "Given name of the privileged user according to Entra ID.", - "maxLength": 64, - "type": "string", - "examples": [ - "John" - ] - }, - "id": { - "description": "The Entra ID Object ID of the managed user. This is the one property that is stored in the settings engine. This is the key in the storage systems to uniquely separate the managed user's data from others.", - "examples": [ - "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" - }, - "intermediaryAssignmentList": { - "type": "array", - "description": "List of intermediaries that the user is assigned to.", - "items": { - "type": "string", - "format": "uuid" - }, - "examples": [ - [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - ] - }, - "lastName": { - "description": "Surname/family name of the privileged user according to Entra ID.", - "maxLength": 64, - "type": "string", - "examples": [ - "Doe" - ] - }, - "upn": { - "description": "User principal name of the user object according to Azure Active Directory.", - "examples": [ - "priv-user@example.com" - ], - "format": "email", - "maxLength": 113, - "minLength": 6, - "type": "string" - }, - "securityClass": { - "$ref": "#/components/schemas/SecurityClassList" - }, - "siloAssignmentList": { - "type": "array", - "description": "List of silos that the user is assigned to.", - "items": { - "type": "string", - "format": "uuid" - }, - "examples": [ - [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - ] - }, - "uiEducation": { - "description": "Indicates if user education is enabled in the UI for the specified user. True is on, false is off.", - "examples": [ - false - ], - "type": "boolean" - }, - "uniqueGroupId": { - "description": "ObjectID of the unique user group that the managed user is a member of.", - "examples": [ - "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d" - ], - "format": "uuid", - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" - } + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Get Specified Device by ID", + "tags": ["Device Management"] + } + }, + "/Api/Defend/User/Type/{securityClass}": { + "get": { + "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", + "operationId": "/Api/Defend/User/Type/:securityClass/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/nextLink" + }, + { + "$ref": "#/components/parameters/search" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObjectPage.ManagedUser" }, - "required": [ - "creationDate", - "securityClass", - "id", - "intermediaryAssignmentList", - "siloAssignmentList", - "uiEducation", - "uniqueGroupId", - "upn" - ], - "type": "object", - "examples": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ + "examples": { + "Managed user": { + "summary": "Example paged user list", + "description": "An examples of ObjectPage.ManagedUser returned that represents a page of a managed user list.", + "value": { + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", "593d97dc-9a43-4bc7-9d79-ecde407d7782", "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ + ], + "siloAssignmentList": [ "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", "593d97dc-9a43-4bc7-9d79-ecde407d7782", "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - ] - }, - "ManagedObject.PrivilegedUser": { - "title": "Managed User - Privileged", - "description": "Additional settings that represents a privileged user object. All data in this structure is preserved in the settings engine's permanent storage system.", - "allOf": [ - { - "$ref": "#/components/schemas/ManagedObject.User" - }, - { - "properties": { - "deviceAssignmentList": { - "type": "array", - "description": "List of devices that the privileged users are able to use as endpoints.", - "items": { - "type": "string", - "format": "uuid" - }, - "examples": [ - [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - ] - }, - "generatedPassword": { - "description": "The password that was created for the managed user upon managed user creation, this is not stored. This is only available once during user creation. If the password is lost, reset the PWD in Entra ID or have the user perform SSPR.", - "examples": [ - "GY_w7bZUKRgpIXctD0S2wg" - ], - "readOnly": true, - "type": "string" - }, - "parentId": { - "description": "The Entra ID Object ID of the object that the manged user is tied to. This value is only present on privileged users.", - "examples": [ - "e59a3a64-dc36-4368-80ec-c205eb176ef6" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "readOnly": true, - "type": "string" - }, - "securityClass": { - "$ref": "#/components/schemas/SecurityClassList" - }, - "temporaryAccessPass": { - "description": "A TAP that was created for the managed user upon managed user creation, this is not stored. This is only available once during user creation. TAP expires at the configured tenant expiration time.", - "examples": [ - "BCKTSN#E2R&5" - ], - "readOnly": true, - "type": "string" - } + ] }, - "required": [ - "deviceAssignmentList", - "parentId", - "securityClass" - ], - "type": "object" - } - ], - "examples": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "deviceAssignmentList": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", "593d97dc-9a43-4bc7-9d79-ecde407d7782", "995f3b39-1e01-40d4-9368-ee956343e97c" @@ -3891,1091 +6037,193 @@ "type": "string", "description": "Flat path representing entire item or specific nested property in the configuration item.", "examples": [ - "/description" - ] - }, - "examples": [ - [ - "/", - "/description" - ] - ] - }, - "description": "Collection of references to configuration items (using templateId property as property name) and array of strings as value.", - "examples": [ - { - "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ - "/" - ], - "9c858901-8a57-4791-81fe-4c455b099bc9": [ - "/description", - "/name" - ] - } - ] - } - } - }, - "description": "OK" - } - }, - "tags": [ - "Deploy" - ] - } - }, - "/Api/Deploy/Skip/{templateId}": { - "post": { - "summary": "Records New Entry to Skip During Evaluation", - "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Skip/:templateId/Post", - "parameters": [ - { - "$ref": "#/components/parameters/templateId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Deploy.PathIndicator" - } - } - } - }, - "responses": { - "204": { - "description": "Recorded successfully" - }, - "400": { - "description": "The body does not match expected format!" - } - }, - "tags": [ - "Deploy" - ] - }, - "delete": { - "summary": "Removes Existing Entry From Being Skipped", - "description": "Deletes the entry so it is no longer ignored during the evaluation process.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Skip/:templateId/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/templateId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Deploy.PathIndicator" - } - } - } - }, - "responses": { - "204": { - "description": "Record has been removed successfully" - }, - "400": { - "description": "The body does not match expected format!" - } - }, - "tags": [ - "Deploy" - ] - } - }, - "/Api/Deploy/Restore/{templateId}": { - "patch": { - "summary": "Restores the Details Of the Deployed Resource", - "description": "Calculates and applies a change to the deployed resource to restore original value from the entire configuration item or single property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Restore/:templateId/Patch", - "parameters": [ - { - "$ref": "#/components/parameters/templateId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Deploy.PathIndicator" - } - } - } - }, - "responses": { - "204": { - "description": "Restoration of configuration item or its property is successful" - }, - "400": { - "description": "The body does not match expected format!" - }, - "404": { - "$ref": "#/components/responses/404" - } - }, - "tags": [ - "Deploy" - ] - } - }, - "/Api/Deploy/Remove": { - "get": { - "summary": "Indicates if the Remove Function Can Be Ran", - "description": "Provides a flag that indicates if the core infrastructure removal command can be ran or not.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Remove/Get", - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "boolean" - }, - "examples": { - "Remove Ready": { - "value": true, - "summary": "Removal Ready", - "description": "Flag that indicates that no dependent components are present and the core infra can be removed." - }, - "Remove Not Ready": { - "value": false, - "summary": "Removal Not Ready", - "description": "Flag that indicates that dependent components are present and the core infra should not be removed." - } - } - } - }, - "description": "OK" - }, - "503": { - "description": "Deployed architecture is invalid or missing!" - } - }, - "tags": [ - "Deploy" - ] - }, - "delete": { - "summary": "Removes All Provisioned Infrastructure Resources", - "description": "Deletes all resources in the tenant that were created during the initial deploy or any update operation since.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/DeployRemove/Delete", - "responses": { - "202": { - "description": "Request for removal is accepted and process initiated" - }, - "503": { - "description": "Deployed architecture is invalid or missing!" - } - }, - "tags": [ - "Deploy" - ] - } - }, - "/Api/Defend/Intermediary/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { - "get": { - "description": "Retrieves a list of all AVD intermediaries for the specified security class filter. Next links may be provided for pagination to allow for good performance on larger environments. If a nextLink is return, not all data was returned on this query and the next link can be sent back to the API to get the next page of data.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/Type/:securityClass/Offering/AVD/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/nextLink" - }, - { - "$ref": "#/components/parameters/search" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" - }, - "examples": { - "Paged AVD intermediaries": { - "summary": "Example paged AVD intermediary list", - "description": "An example paged AVD intermediary list returned that represents the current page of all AVD intermediary instances form the specified security class.", - "value": { - "@odata.count": 1, - "@odata.nextLink": "1", - "value": [ - { - "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "kind": "AVD", - "name": "Legacy Reach Back", - "securityClass": "Privileged", - "addressRangeCIDR": "172.16.1.0/24", - "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", - "index": 0, - "location": "East US 2", - "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", - "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - ] - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Retrieves all AVD Intermediary Instances", - "tags": [ - "Intermediary" - ] - } - }, - "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { - "delete": { - "description": "Deletes the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - } - ], - "responses": { - "204": { - "description": "OK: Deleted successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Deletes a Single AVD Intermediary Instance", - "tags": [ - "Intermediary" - ] - }, - "get": { - "description": "Retrieves the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" - }, - "examples": { - "Paged AVD intermediary result": { - "summary": "Example paged result of a AVD intermediary list", - "description": "An example paged result that represents the current page of retrieved AVD intermediary list from a parent group filtered by specified class.", - "value": { - "@odata.count": 1, - "@odata.nextLink": "1", - "value": [ - { - "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "kind": "AVD", - "name": "Legacy Reach Back", - "securityClass": "Privileged", - "addressRangeCIDR": "172.16.1.0/24", - "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", - "index": 0, - "location": "East US 2", - "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", - "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - ] - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Retrieves a Single AVD Intermediary Instance", - "tags": [ - "Intermediary" - ] - } - }, - "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign": { - "delete": { - "description": "Removes the specified user(s) as identified by their Object ID from the AVD cluster and deletes their corresponding session host(s).\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - } - ], - "requestBody": { - "content": { - "application/json": { - "examples": { - "One user": { - "description": "Removes 1 session host, and removed the requested user from the assignments security group.", - "summary": "Remove Single User", - "value": { - "userList": [ - "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" - ] - } - }, - "Two users": { - "description": "Removes 3 session hosts, and removed the requested users from the assignments security group.", - "summary": "Remove Multiple Users", - "value": { - "userList": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc", - "dd27937c-6287-45b3-98de-387725b068f3", - "989d3dc1-43f4-4ff7-82ba-43661f94a428" - ] - } - } - }, - "schema": { - "properties": { - "userList": { - "items": { - "format": "uuid", - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - } - } - } - }, - "responses": { - "204": { - "description": "OK: Deleted successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Removes the assignment of the specified users", - "tags": [ - "Intermediary" - ] - }, - "get": { - "description": "Gets the list of assigned user from the specified AVD Intermediary.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - }, - { - "$ref": "#/components/parameters/nextLink" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ObjectPage.ManagedUser" - }, - "examples": { - "Managed user page": { - "summary": "Example paged user result", - "description": "An example of paged user result that represents the current page of assigned user list retrieved from the specified AVD intermediary.", - "value": { - "@odata.count": 3, - "@odata.nextLink": "2", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - }, - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "deviceAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", - "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", - "temporaryAccessPass": "BCKTSN#E2R&5" - } - ] - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "List all assigned users (paginated)", - "tags": [ - "Intermediary" - ] - }, - "post": { - "description": "Assigns the specified user(s) as identified by their Object ID to the AVD cluster and create corresponding session host(s) for them.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Post", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - } - ], - "requestBody": { - "content": { - "application/json": { - "examples": { - "One user": { - "description": "Creates 1 session host, and added the requested user to the assignments security group.", - "summary": "Assign Single User", - "value": { - "userList": [ - "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" - ] - } - }, - "Two users": { - "description": "Creates 3 session hosts, and added the requested users to the assignments security group.", - "summary": "Assign Multiple Users", - "value": { - "userList": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc", - "dd27937c-6287-45b3-98de-387725b068f3", - "989d3dc1-43f4-4ff7-82ba-43661f94a428" - ] - } - } - }, - "schema": { - "properties": { - "userList": { - "items": { - "format": "uuid", - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string", - "examples": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc" - ] - }, - "type": "array", - "examples": [ - [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc" - ] - ] - } - }, - "type": "object", - "examples": [ - { - "userList": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc" - ] - } - ] - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/ManagedObject.User" - }, - "minItems": 0, - "type": "array" - }, - "examples": { - "Managed user": { - "summary": "Example managed users returned", - "description": "An example of managed user array returned that represents the users has been assigned to the specified AVD cluster and created corresponding session host successfully.", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - ] - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Assigns the list of specified users", - "tags": [ - "Intermediary" - ] - } - }, - "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign/{userId}": { - "get": { - "description": "Get the specified managed user(s) from the specified AVD intermediary assignment list.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/:userId/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - }, - { - "$ref": "#/components/parameters/userId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ObjectPage.ManagedUser" - }, - "examples": { - "Assigned users": { - "summary": "Example assigned user list", - "description": "An example paged assigned user list that represents the current page retrieved from specified AVD intermediary assignment list.", - "value": { - "@odata.count": 3, - "@odata.nextLink": "2", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - }, - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "deviceAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", - "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", - "temporaryAccessPass": "BCKTSN#E2R&5" - } + "/description" + ] + }, + "examples": [ + [ + "/", + "/description" + ] + ] + }, + "description": "Collection of references to configuration items (using templateId property as property name) and array of strings as value.", + "examples": [ + { + "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ + "/" + ], + "9c858901-8a57-4791-81fe-4c455b099bc9": [ + "/description", + "/name" ] } - } + ] } } }, "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" } }, - "summary": "Get a specific assigned user", "tags": [ - "Intermediary" + "Deploy" ] } }, - "/Api/Defend/Device/{deviceId}/Type/Privileged/Assign": { - "delete": { - "description": "Remove the specified user list from the device.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Delete", + "/Api/Deploy/Skip/{templateId}": { + "post": { + "summary": "Records New Entry to Skip During Evaluation", + "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/:templateId/Post", "parameters": [ { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/templateId" } ], "requestBody": { "content": { "application/json": { - "examples": { - "Multiple Users": { - "description": "Remove multiple user assignments from a managed device.", - "summary": "Unassign multiple users", - "value": { - "userList": [ - "0674276a-31e8-4773-8ed9-6fb49dbd0fa8", - "66714224-b1a6-4fd6-b9d8-5263fdf755fc" - ] - } - }, - "Single User": { - "description": "Remove a single user assignment from a managed device.", - "summary": "Unassign one user", - "value": { - "userList": [ - "01ebf268-cf28-4607-954a-261dfd480453" - ] - } - } - }, "schema": { - "properties": { - "userList": { - "items": { - "examples": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ], - "format": "uuid", - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "type": "array", - "examples": [ - [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ] - ] - } - }, - "type": "object", - "examples": [ - { - "userList": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ] - } - ] + "$ref": "#/components/schemas/Deploy.PathIndicator" } } } }, "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/ManagedObject.User" - }, - "minItems": 0, - "type": "array" - }, - "examples": { - "Removed user list": { - "summary": "Example removed user list", - "description": "An example array of ManagedObject.User that represents those removed from specific privileged device assignment.", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - ] - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" + "204": { + "description": "Recorded successfully" }, - "525": { - "$ref": "#/components/responses/525" + "400": { + "description": "The body does not match expected format!" } }, - "summary": "Remove User Assignments", "tags": [ - "Device Management" + "Deploy" ] }, - "get": { - "description": "Lists all of the users that are currently assigned to the specified device.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Get", + "delete": { + "summary": "Removes Existing Entry From Being Skipped", + "description": "Deletes the entry so it is no longer ignored during the evaluation process.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/:templateId/Delete", "parameters": [ { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/templateId" } ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ObjectPage.ManagedUser" - }, - "examples": { - "Example response": { - "summary": "Example paged response", - "description": "An example of ObjectPage.ManagedUser returned that represents the list of users assigned to specific privileged device.", - "value": { - "@odata.count": 3, - "@odata.nextLink": "2", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - }, - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "deviceAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", - "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", - "temporaryAccessPass": "BCKTSN#E2R&5" - } - ] - } - } - } + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.PathIndicator" } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" + } + } + }, + "responses": { + "204": { + "description": "Record has been removed successfully" }, - "525": { - "$ref": "#/components/responses/525" + "400": { + "description": "The body does not match expected format!" } }, - "summary": "List User Assignments", "tags": [ - "Device Management" + "Deploy" ] - }, - "post": { - "description": "Adds the specified list of users to the list of users that are allowed to log in on the specific privileged device.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Post", + } + }, + "/Api/Deploy/Restore/{templateId}": { + "patch": { + "summary": "Restores the Details Of the Deployed Resource", + "description": "Calculates and applies a change to the deployed resource to restore original value from the entire configuration item or single property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Restore/:templateId/Patch", "parameters": [ { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/templateId" } ], "requestBody": { "content": { "application/json": { - "examples": { - "1:1 map": { - "description": "This example is the security best practice of having only one user mapped to a managed device.", - "summary": "1:1 User Mapping", - "value": { - "userList": [ - "0674276a-31e8-4773-8ed9-6fb49dbd0fa8" - ] - } - }, - "Multi-User Managed Device": { - "description": "This example is the security best practice of having multiple users mapped to a managed device.", - "summary": "Multi-User Assignment", - "value": { - "userList": [ - "0674276a-31e8-4773-8ed9-6fb49dbd0fa8", - "66714224-b1a6-4fd6-b9d8-5263fdf755fc" - ] - } - } - }, "schema": { - "properties": { - "userList": { - "items": { - "examples": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ], - "format": "uuid", - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "type": "array", - "examples": [ - [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ] - ] - } - }, - "type": "object", - "examples": [ - { - "userList": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ] - } - ] + "$ref": "#/components/schemas/Deploy.PathIndicator" } } } }, + "responses": { + "204": { + "description": "Restoration of configuration item or its property is successful" + }, + "400": { + "description": "The body does not match expected format!" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Remove": { + "get": { + "summary": "Indicates if the Remove Function Can Be Ran", + "description": "Provides a flag that indicates if the core infrastructure removal command can be ran or not.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Remove/Get", "responses": { "200": { "content": { "application/json": { "schema": { - "items": { - "$ref": "#/components/schemas/ManagedObject.User" - }, - "minItems": 0, - "type": "array" + "type": "boolean" }, "examples": { - "List of Managed Users": { - "summary": "Users assigned to the privileged device", - "description": "An example of ManagedObject.User array that represents the list of users which successfully assigned to the specified privileged device.", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - ] + "Remove Ready": { + "value": true, + "summary": "Removal Ready", + "description": "Flag that indicates that no dependent components are present and the core infra can be removed." + }, + "Remove Not Ready": { + "value": false, + "summary": "Removal Not Ready", + "description": "Flag that indicates that dependent components are present and the core infra should not be removed." } } } }, "description": "OK" }, - "401": { - "$ref": "#/components/responses/401" + "503": { + "description": "Deployed architecture is invalid or missing!" + } + }, + "tags": [ + "Deploy" + ] + }, + "delete": { + "summary": "Removes All Provisioned Infrastructure Resources", + "description": "Deletes all resources in the tenant that were created during the initial deploy or any update operation since.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/DeployRemove/Delete", + "responses": { + "202": { + "description": "Request for removal is accepted and process initiated" }, - "525": { - "$ref": "#/components/responses/525" + "503": { + "description": "Deployed architecture is invalid or missing!" } }, - "summary": "Add User Assignments", "tags": [ - "Device Management" + "Deploy" ] } }, - "/Api/Defend/Device/Type/{securityClass}": { + "/Api/Defend/Intermediary/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { "get": { - "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", - "operationId": "/Api/Defend/Device/Type/:securityClass/Get", + "description": "Retrieves a list of all AVD intermediaries for the specified security class filter. Next links may be provided for pagination to allow for good performance on larger environments. If a nextLink is return, not all data was returned on this query and the next link can be sent back to the API to get the next page of data.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/Type/:securityClass/Offering/AVD/Get", "parameters": [ { "$ref": "#/components/parameters/securityClass" @@ -4992,38 +6240,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ObjectPage.ManagedDevice" + "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" }, "examples": { - "Managed device list": { - "summary": "Example list of managed devices", - "description": "An example paged result returned that represents a specific page of managed device list.", + "Paged AVD intermediaries": { + "summary": "Example paged AVD intermediary list", + "description": "An example paged AVD intermediary list returned that represents the current page of all AVD intermediary instances form the specified security class.", "value": { - "@odata.count": 3, - "@odata.nextLink": "2", + "@odata.count": 1, + "@odata.nextLink": "1", "value": [ { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "securityClass": "Privileged", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" - }, - { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", - "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", "securityClass": "Privileged", - "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", - "userAssignmentList": [ - "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", - "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", - "c54d4854-9254-4689-8a22-1cc80a3dae4e" - ] + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" } ] } @@ -5040,109 +6279,22 @@ "$ref": "#/components/responses/525" } }, - "summary": "Get All Devices", - "tags": [ - "Device Management" - ] - }, - "post": { - "description": "Commissions a new device, into the device hierarchy and appends appropriate metadata and initial policies. Appends required metadata to proper locations.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Device/Type/:securityClass/Post", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - } - ], - "requestBody": { - "content": { - "application/json": { - "examples": { - "Request body": { - "value": { - "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" - }, - "summary": "Example request body", - "description": "An example request body object that represents a request to commission the device specified in the deviceId field." - } - }, - "schema": { - "properties": { - "deviceId": { - "description": "The SHIELD ID (Entra ID Device ID) of the device to target.", - "examples": [ - "75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - } - }, - "required": [ - "deviceId" - ], - "type": "object", - "examples": [ - { - "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" - } - ] - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ManagedObject.Device" - }, - "examples": { - "Commissioned managed device": { - "summary": "Example managed device info", - "description": "An example managed device object returned that represents a successfully commissioned device.", - "value": { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "securityClass": "Privileged", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Commission a New Device", + "summary": "Retrieves all AVD Intermediary Instances", "tags": [ - "Device Management" + "Intermediary" ] } }, - "/Api/Defend/Device/{deviceId}/Type/{securityClass}": { + "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { "delete": { - "description": "Removes the device from the management hierarchy, removes metadata tagging and issues the wipe command to the devices.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Delete", + "description": "Deletes the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Delete", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/intermediaryId" } ], "responses": { @@ -5159,20 +6311,20 @@ "$ref": "#/components/responses/525" } }, - "summary": "Decommission Specified Device", + "summary": "Deletes a Single AVD Intermediary Instance", "tags": [ - "Device Management" + "Intermediary" ] }, "get": { - "description": "Get the specified managed device by its Entra ID Device ID.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Get", + "description": "Retrieves the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Get", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/intermediaryId" } ], "responses": { @@ -5180,19 +6332,31 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ManagedObject.Device" + "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" }, "examples": { - "Managed device": { - "summary": "Example managed device", - "description": "An example of ManagedObject.Device object returned that represents a managed device queried by a device ID with specified security class.", + "Paged AVD intermediary result": { + "summary": "Example paged result of a AVD intermediary list", + "description": "An example paged result that represents the current page of retrieved AVD intermediary list from a parent group filtered by specified class.", "value": { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "securityClass": "Privileged", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + "@odata.count": 1, + "@odata.nextLink": "1", + "value": [ + { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged", + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + ] } } } @@ -5210,25 +6374,96 @@ "$ref": "#/components/responses/525" } }, - "summary": "Get Specified Device by ID", + "summary": "Retrieves a Single AVD Intermediary Instance", "tags": [ - "Device Management" + "Intermediary" ] } }, - "/Api/Defend/User/Type/{securityClass}": { + "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign": { + "delete": { + "description": "Removes the specified user(s) as identified by their Object ID from the AVD cluster and deletes their corresponding session host(s).\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "One user": { + "description": "Removes 1 session host, and removed the requested user from the assignments security group.", + "summary": "Remove Single User", + "value": { + "userList": [ + "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" + ] + } + }, + "Two users": { + "description": "Removes 3 session hosts, and removed the requested users from the assignments security group.", + "summary": "Remove Multiple Users", + "value": { + "userList": [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc", + "dd27937c-6287-45b3-98de-387725b068f3", + "989d3dc1-43f4-4ff7-82ba-43661f94a428" + ] + } + } + }, + "schema": { + "properties": { + "userList": { + "items": { + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + } + } + }, + "responses": { + "204": { + "description": "OK: Deleted successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Removes the assignment of the specified users", + "tags": [ + "Intermediary" + ] + }, "get": { - "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", - "operationId": "/Api/Defend/User/Type/:securityClass/Get", + "description": "Gets the list of assigned user from the specified AVD Intermediary.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Get", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { - "$ref": "#/components/parameters/nextLink" + "$ref": "#/components/parameters/intermediaryId" }, { - "$ref": "#/components/parameters/search" + "$ref": "#/components/parameters/nextLink" } ], "responses": { @@ -5239,9 +6474,9 @@ "$ref": "#/components/schemas/ObjectPage.ManagedUser" }, "examples": { - "Managed user": { - "summary": "Example paged user list", - "description": "An examples of ObjectPage.ManagedUser returned that represents a page of a managed user list.", + "Managed user page": { + "summary": "Example paged user result", + "description": "An example of paged user result that represents the current page of assigned user list retrieved from the specified AVD intermediary.", "value": { "@odata.count": 3, "@odata.nextLink": "2", @@ -5307,322 +6542,412 @@ "401": { "$ref": "#/components/responses/401" }, + "404": { + "$ref": "#/components/responses/404" + }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "Get All Users", + "summary": "List all assigned users (paginated)", "tags": [ - "User Management" + "Intermediary" ] }, "post": { - "description": "For Specialized or Enterprise, adds existing user into management. For Privileged, securely clones the specified user's properties into a new managed user object in the privileged baselines.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/User/Type/:securityClass/Post", + "description": "Assigns the specified user(s) as identified by their Object ID to the AVD cluster and create corresponding session host(s) for them.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Post", "parameters": [ { "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" } ], "requestBody": { "content": { "application/json": { "examples": { - "Request body": { + "One user": { + "description": "Creates 1 session host, and added the requested user to the assignments security group.", + "summary": "Assign Single User", "value": { - "userId": "d886680d-a283-4fc2-803f-370d81d62366" - }, - "summary": "Example request body", - "description": "An example object that represents a request to assign the specified user to target security class." + "userList": [ + "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" + ] + } + }, + "Two users": { + "description": "Creates 3 session hosts, and added the requested users to the assignments security group.", + "summary": "Assign Multiple Users", + "value": { + "userList": [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc", + "dd27937c-6287-45b3-98de-387725b068f3", + "989d3dc1-43f4-4ff7-82ba-43661f94a428" + ] + } } }, "schema": { "properties": { - "userId": { - "description": "The Entra ID object ID of the user to clone.", + "userList": { + "items": { + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string", + "examples": [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc" + ] + }, + "type": "array", "examples": [ - "264a8bed-0714-48fd-8b9d-0e4c4715cee5" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc" + ] + ] } }, - "required": [ - "userId" - ], "type": "object", "examples": [ { - "userId": "264a8bed-0714-48fd-8b9d-0e4c4715cee5" + "userList": [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc" + ] } ] } } + ] } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Get All Users", + "tags": ["User Management"] + }, + "post": { + "description": "For Specialized or Enterprise, adds existing user into management. For Privileged, securely clones the specified user's properties into a new managed user object in the privileged baselines.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/User/Type/:securityClass/Post", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Request body": { + "value": { + "userId": "d886680d-a283-4fc2-803f-370d81d62366" + }, + "summary": "Example request body", + "description": "An example object that represents a request to assign the specified user to target security class." + } + }, + "schema": { + "properties": { + "userId": { + "description": "The Entra ID object ID of the user to clone.", + "examples": ["264a8bed-0714-48fd-8b9d-0e4c4715cee5"], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + } }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ManagedObject.User" - }, - "examples": { - "Created or cloned user": { - "summary": "Example user created/cloned", - "description": "An example managed user object returned that represents the user brought into management successfully.", - "value": { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "409": { - "description": "User is already managed." - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Create/Bring User Into Management", - "tags": [ - "User Management" + "required": ["userId"], + "type": "object", + "examples": [ + { + "userId": "264a8bed-0714-48fd-8b9d-0e4c4715cee5" + } ] + } } + } }, - "/Api/Defend/User/{userId}/Type/{securityClass}": { - "delete": { - "description": "Deletes the user account and removes the management artifacts.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/userId" - } - ], - "responses": { - "204": { - "description": "OK: Deleted successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.User" }, - "summary": "Delete Managed User by ID", - "tags": [ - "User Management" - ] + "examples": { + "Created or cloned user": { + "summary": "Example user created/cloned", + "description": "An example managed user object returned that represents the user brought into management successfully.", + "value": { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + } + } + } + } }, - "get": { - "description": "Retrieves the specified managed user by its Entra ID User ID.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/userId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ManagedObject.User" - }, - "examples": { - "Removed user": { - "summary": "Example removed user", - "description": "An example of managed user returned that represents the user has been removed from specified security class successfully.", - "value": { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "409": { + "description": "User is already managed." + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Create/Bring User Into Management", + "tags": ["User Management"] + } + }, + "/Api/Defend/User/{userId}/Type/{securityClass}": { + "delete": { + "description": "Deletes the user account and removes the management artifacts.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/userId" + } + ], + "responses": { + "204": { + "description": "OK: Deleted successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Delete Managed User by ID", + "tags": ["User Management"] + }, + "get": { + "description": "Retrieves the specified managed user by its Entra ID User ID.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/userId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.User" }, - "summary": "Gets Managed User by ID", - "tags": [ - "User Management" - ] - } + "examples": { + "Removed user": { + "summary": "Example removed user", + "description": "An example of managed user returned that represents the user has been removed from specified security class successfully.", + "value": { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } }, - "/Api/Defend/Marketplace/Type/{securityClass}/Offering/{offeringId}": { - "post": { - "description": "Creates the offering with the requested settings. In the body payload, the `type` property in the `property` object is ignored. See the AVD example.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Marketplace/Type/:securityClass/Offering/:offeringId/Post", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" + "summary": "Gets Managed User by ID", + "tags": ["User Management"] + } + }, + "/Api/Defend/Marketplace/Type/{securityClass}/Offering/{offeringId}": { + "post": { + "description": "Creates the offering with the requested settings. In the body payload, the `type` property in the `property` object is ignored. See the AVD example.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Marketplace/Type/:securityClass/Offering/:offeringId/Post", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/offeringId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ManagedObject.Intermediary" + }, + { + "properties": { + "properties": { + "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" + } }, - { - "$ref": "#/components/parameters/offeringId" - } + "type": "object" + } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/ManagedObject.Intermediary" - }, - { - "properties": { - "properties": { - "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" - } - }, - "type": "object" - } - ], - "examples": [ - { - "name": "Legacy Reach Back", - "properties": { - "addressRangeCIDR": "172.16.1.0/24", - "index": 0, - "location": "East US 2", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - } - ] - }, - "examples": { - "Example intermediary object request": { - "summary": "Example Intermediary object request", - "description": "An example of create offering request body with minimal fields.", - "value": { - "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "kind": "AVD", - "name": "Legacy Reach Back", - "securityClass": "Privileged", - "properties": { - "addressRangeCIDR": "172.16.1.0/24", - "index": 0, - "location": "East US 2", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - } - } - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" - }, - "examples": { - "Returned AVD intermediary": { - "summary": "Example AVD intermediary returned", - "description": "An example of AVD intermediary object returned that represents an successfully deployed offering.", - "value": { - "addressRangeCIDR": "172.16.1.0/24", - "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", - "index": 0, - "location": "East US 2", - "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", - "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" + "examples": [ + { + "name": "Legacy Reach Back", + "properties": { + "addressRangeCIDR": "172.16.1.0/24", + "index": 0, + "location": "East US 2", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" } - }, - "summary": "Deploy Marketplace Offering", - "tags": [ - "Marketplace" + } ] + }, + "examples": { + "Example intermediary object request": { + "summary": "Example Intermediary object request", + "description": "An example of create offering request body with minimal fields.", + "value": { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged", + "properties": { + "addressRangeCIDR": "172.16.1.0/24", + "index": 0, + "location": "East US 2", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + } + } + } } - } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" + }, + "examples": { + "Returned AVD intermediary": { + "summary": "Example AVD intermediary returned", + "description": "An example of AVD intermediary object returned that represents an successfully deployed offering.", + "value": { + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" + } + }, + "summary": "Deploy Marketplace Offering", + "tags": ["Marketplace"] + } + } + }, + "security": [ + { + "EntraID": [] + } + ], + "servers": [ + { + "description": "The service", + "url": "/" + } + ], + "tags": [ + { + "description": "Configures the specified web server to support and process the authentication API routes.", + "name": "Core" }, "security": [ {