Microsoft Entra ID (formerly Azure AD) Identity Protection.risk Detection API

openapi: 3.2.0
info:
  title: Identity.SignIns Identity Protection.risk Detection API
  version: v1.0
servers:
- url: https://graph.microsoft.com/v1.0/
  description: Core
security:
- azureaadv2: []
tags:
- name: identityProtection.riskDetection
paths:
  /identityProtection/riskDetections:
    get:
      tags:
      - identityProtection.riskDetection
      summary: List riskDetections
      description: Get a list of the riskDetection objects and their properties.
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/riskdetection-list?view=graph-rest-1.0
      operationId: identityProtection_ListRiskDetection
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/count'
      - name: $orderby
        in: query
        description: Order items by property values
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: $select
        in: query
        description: Select properties to be returned
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: $expand
        in: query
        description: Expand related entities
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        2XX:
          $ref: '#/components/responses/microsoft.graph.riskDetectionCollectionResponse'
        default:
          $ref: '#/components/responses/error'
      x-ms-pageable:
        nextLinkName: '@odata.nextLink'
        operationName: listMore
      x-ms-docs-operation-type: operation
    post:
      tags:
      - identityProtection.riskDetection
      summary: Create new navigation property to riskDetections for identityProtection
      operationId: identityProtection_CreateRiskDetection
      requestBody:
        description: New navigation property
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/microsoft.graph.riskDetection'
        required: true
      responses:
        2XX:
          description: Created navigation property.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.riskDetection'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /identityProtection/riskDetections/{riskDetection-id}:
    get:
      tags:
      - identityProtection.riskDetection
      summary: Get riskDetection
      description: Read the properties and relationships of a riskDetection object.
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/riskdetection-get?view=graph-rest-1.0
      operationId: identityProtection_GetRiskDetection
      parameters:
      - name: riskDetection-id
        in: path
        description: The unique identifier of riskDetection
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: riskDetection
      - name: $select
        in: query
        description: Select properties to be returned
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: $expand
        in: query
        description: Expand related entities
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        2XX:
          description: Retrieved navigation property
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.riskDetection'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    patch:
      tags:
      - identityProtection.riskDetection
      summary: Update the navigation property riskDetections in identityProtection
      operationId: identityProtection_UpdateRiskDetection
      parameters:
      - name: riskDetection-id
        in: path
        description: The unique identifier of riskDetection
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: riskDetection
      requestBody:
        description: New navigation property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/microsoft.graph.riskDetection'
        required: true
      responses:
        2XX:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.riskDetection'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
      - identityProtection.riskDetection
      summary: Delete navigation property riskDetections for identityProtection
      operationId: identityProtection_DeleteRiskDetection
      parameters:
      - name: riskDetection-id
        in: path
        description: The unique identifier of riskDetection
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: riskDetection
      - name: If-Match
        in: header
        description: ETag
        style: simple
        schema:
          type: string
      responses:
        2XX:
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /identityProtection/riskDetections/$count:
    get:
      tags:
      - identityProtection.riskDetection
      summary: Get the number of the resource
      operationId: identityProtection.riskDetection_GetCount
      parameters:
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/filter'
      responses:
        2XX:
          $ref: '#/components/responses/ODataCountResponse'
        default:
          $ref: '#/components/responses/error'
components:
  responses:
    error:
      description: error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ODataError'
    microsoft.graph.riskDetectionCollectionResponse:
      description: Retrieved collection
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/microsoft.graph.riskDetectionCollectionResponse'
    ODataCountResponse:
      description: The count of the resource
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/ODataCountResponse'
  schemas:
    microsoft.graph.riskState:
      title: riskState
      enum:
      - none
      - confirmedSafe
      - remediated
      - dismissed
      - atRisk
      - confirmedCompromised
      - unknownFutureValue
      type: string
    microsoft.graph.ODataErrors.MainError:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
          x-ms-primary-error-message: true
        target:
          type:
          - string
          - 'null'
        details:
          type: array
          items:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ErrorDetails'
        innerError:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.InnerError'
      additionalProperties:
        type: object
    ODataCountResponse:
      type: integer
      format: int32
    microsoft.graph.riskDetectionTimingType:
      title: riskDetectionTimingType
      enum:
      - notDefined
      - realtime
      - nearRealtime
      - offline
      - unknownFutureValue
      type: string
    microsoft.graph.riskDetection:
      allOf:
      - $ref: '#/components/schemas/microsoft.graph.entity'
      - title: riskDetection
        type: object
        properties:
          activity:
            $ref: '#/components/schemas/microsoft.graph.activityType'
          activityDateTime:
            pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
            type:
            - string
            - 'null'
            description: 'Date and time that the risky activity occurred. The DateTimeOffset type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is look like this: 2014-01-01T00:00:00Z'
            format: date-time
          additionalInfo:
            type:
            - string
            - 'null'
            description: 'Additional information associated with the risk detection in JSON format. For example, ''[{/''Key/'':/''userAgent/'',/''Value/'':/''Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36/''}]''. Possible keys in the additionalInfo JSON string are: userAgent, alertUrl, relatedEventTimeInUtc, relatedUserAgent, deviceInformation, relatedLocation, requestId, correlationId, lastActivityTimeInUtc, malwareName, clientLocation, clientIp, riskReasons. For more information about riskReasons and possible values, see riskReasons values.'
          correlationId:
            type:
            - string
            - 'null'
            description: Correlation ID of the sign-in associated with the risk detection. This property is null if the risk detection is not associated with a sign-in.
          detectedDateTime:
            pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
            type:
            - string
            - 'null'
            description: 'Date and time that the risk was detected. The DateTimeOffset type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 looks like this: 2014-01-01T00:00:00Z'
            format: date-time
          detectionTimingType:
            $ref: '#/components/schemas/microsoft.graph.riskDetectionTimingType'
          ipAddress:
            type:
            - string
            - 'null'
            description: Provides the IP address of the client from where the risk occurred.
          lastUpdatedDateTime:
            pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
            type:
            - string
            - 'null'
            description: 'Date and time that the risk detection was last updated. The DateTimeOffset type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is look like this: 2014-01-01T00:00:00Z'
            format: date-time
          location:
            $ref: '#/components/schemas/microsoft.graph.signInLocation'
          requestId:
            type:
            - string
            - 'null'
            description: Request ID of the sign-in associated with the risk detection. This property is null if the risk detection is not associated with a sign-in.
          riskDetail:
            $ref: '#/components/schemas/microsoft.graph.riskDetail'
          riskEventType:
            type:
            - string
            - 'null'
            description: The type of risk event detected. The possible values are adminConfirmedUserCompromised, anomalousToken, anomalousUserActivity, anonymizedIPAddress, generic, impossibleTravel, investigationsThreatIntelligence, suspiciousSendingPatterns, leakedCredentials, maliciousIPAddress,malwareInfectedIPAddress, mcasSuspiciousInboxManipulationRules, newCountry, passwordSpray,riskyIPAddress, suspiciousAPITraffic, suspiciousBrowser,suspiciousInboxForwarding, suspiciousIPAddress, tokenIssuerAnomaly, unfamiliarFeatures, unlikelyTravel. If the risk detection is a premium detection, will show generic. For more information about each value, see Risk types and detection.
          riskLevel:
            $ref: '#/components/schemas/microsoft.graph.riskLevel'
          riskState:
            $ref: '#/components/schemas/microsoft.graph.riskState'
          source:
            type:
            - string
            - 'null'
            description: Source of the risk detection. For example, activeDirectory.
          tokenIssuerType:
            $ref: '#/components/schemas/microsoft.graph.tokenIssuerType'
          userDisplayName:
            type:
            - string
            - 'null'
            description: The user principal name (UPN) of the user.
          userId:
            type:
            - string
            - 'null'
            description: Unique ID of the user.
          userPrincipalName:
            type:
            - string
            - 'null'
            description: The user principal name (UPN) of the user.
        additionalProperties:
          type: object
    microsoft.graph.ODataErrors.InnerError:
      type: object
      additionalProperties:
        type: object
      description: The structure of this object is service-specific
    microsoft.graph.signInLocation:
      title: signInLocation
      type: object
      properties:
        city:
          type:
          - string
          - 'null'
          description: Provides the city where the sign-in originated and is determined using latitude/longitude information from the sign-in activity.
        countryOrRegion:
          type:
          - string
          - 'null'
          description: Provides the country code info (two letter code) where the sign-in originated.  This is calculated using latitude/longitude information from the sign-in activity.
        geoCoordinates:
          $ref: '#/components/schemas/microsoft.graph.geoCoordinates'
        state:
          type:
          - string
          - 'null'
          description: Provides the State where the sign-in originated. This is calculated using latitude/longitude information from the sign-in activity.
      additionalProperties:
        type: object
    microsoft.graph.activityType:
      title: activityType
      enum:
      - signin
      - user
      - unknownFutureValue
      - servicePrincipal
      type: string
    microsoft.graph.geoCoordinates:
      title: geoCoordinates
      type: object
      properties:
        altitude:
          type:
          - number
          - 'null'
          description: Optional. The altitude (height), in feet,  above sea level for the item. Read-only.
          format: double
        latitude:
          type:
          - number
          - 'null'
          description: Optional. The latitude, in decimal, for the item. Read-only.
          format: double
        longitude:
          type:
          - number
          - 'null'
          description: Optional. The longitude, in decimal, for the item. Read-only.
          format: double
      additionalProperties:
        type: object
    microsoft.graph.ODataErrors.ODataError:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.MainError'
      additionalProperties:
        type: object
    microsoft.graph.riskLevel:
      title: riskLevel
      enum:
      - low
      - medium
      - high
      - hidden
      - none
      - unknownFutureValue
      type: string
    microsoft.graph.tokenIssuerType:
      title: tokenIssuerType
      enum:
      - AzureAD
      - ADFederationServices
      - UnknownFutureValue
      - AzureADBackupAuth
      - ADFederationServicesMFAAdapter
      - NPSExtension
      type: string
    microsoft.graph.ODataErrors.ErrorDetails:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type:
          - string
          - 'null'
      additionalProperties:
        type: object
    microsoft.graph.entity:
      title: entity
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for an entity. Read-only.
      additionalProperties:
        type: object
    microsoft.graph.riskDetectionCollectionResponse:
      title: Collection of riskDetection
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/microsoft.graph.riskDetection'
        '@odata.nextLink':
          type:
          - string
          - 'null'
      additionalProperties:
        type: object
    microsoft.graph.riskDetail:
      title: riskDetail
      enum:
      - none
      - adminGeneratedTemporaryPassword
      - userPerformedSecuredPasswordChange
      - userPerformedSecuredPasswordReset
      - adminConfirmedSigninSafe
      - aiConfirmedSigninSafe
      - userPassedMFADrivenByRiskBasedPolicy
      - adminDismissedAllRiskForUser
      - adminConfirmedSigninCompromised
      - hidden
      - adminConfirmedUserCompromised
      - unknownFutureValue
      - m365DAdminDismissedDetection
      - adminConfirmedServicePrincipalCompromised
      - adminDismissedAllRiskForServicePrincipal
      - userChangedPasswordOnPremises
      - adminDismissedRiskForSignIn
      - adminConfirmedAccountSafe
      - microsoftRevokedSessions
      type: string
  parameters:
    filter:
      name: $filter
      in: query
      description: Filter items by property values
      style: form
      explode: false
      schema:
        type: string
    search:
      name: $search
      in: query
      description: Search items by search phrases
      style: form
      explode: false
      schema:
        type: string
    count:
      name: $count
      in: query
      description: Include count of items
      style: form
      explode: false
      schema:
        type: boolean
    skip:
      name: $skip
      in: query
      description: Skip the first n items
      style: form
      explode: false
      schema:
        minimum: 0
        type: integer
    top:
      name: $top
      in: query
      description: Show only the first n items
      style: form
      explode: false
      schema:
        minimum: 0
        type: integer
      example: 50
  securitySchemes:
    azureaadv2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes: {}