openapi: 3.0.3
info:
  title: Microsoft Graph and Service Principals App Role Assignments Applications API
  description: Register and manage Microsoft Entra applications and their associated service principals via Microsoft Graph. Configure app permissions (API permissions), OAuth2 permission grants (delegated consent), app role assignments, certificates, keys, federated identity credentials, and app consent policies. Use this API for application lifecycle management and zero-trust app governance.
  version: v1.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
  termsOfService: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0
security:
- oauth2:
  - Application.Read.All
  - Application.ReadWrite.All
tags:
- name: Applications
paths:
  /applications:
    get:
      operationId: list-applications
      summary: Active Directory List Applications
      description: Retrieve the list of applications registered in the Microsoft Entra tenant. Returns application objects representing registered apps (not service principals). Supports OData query parameters for filtering and pagination.
      tags:
      - Applications
      parameters:
      - name: $filter
        in: query
        description: OData filter expression (e.g. displayName eq 'My App')
        schema:
          type: string
      - name: $select
        in: query
        schema:
          type: string
      - name: $top
        in: query
        schema:
          type: integer
      - name: $search
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Collection of application registrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCollection'
              example:
                '@odata.context': https://graph.microsoft.com/v1.0/$metadata#applications
                value:
                - id: aaa-bbb-ccc-ddd
                  appId: 00000003-0000-0000-c000-000000000000
                  displayName: My Enterprise App
                  signInAudience: AzureADMyOrg
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: Response || 200
    post:
      operationId: create-application
      summary: Active Directory Create Application
      description: Register a new application in Microsoft Entra ID. The application object is the global registration; a service principal is automatically created in the home tenant (or must be created separately in other tenants).
      tags:
      - Applications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreate'
            example:
              displayName: My New Application
              signInAudience: AzureADMyOrg
      responses:
        '201':
          description: Application registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: Response || 201
  /applications/{applicationId}:
    get:
      operationId: get-application
      summary: Active Directory Get Application
      description: Retrieve the properties of an application registration by its object ID.
      tags:
      - Applications
      parameters:
      - name: applicationId
        in: path
        required: true
        description: Application object ID (not the appId/client ID)
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Application object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: Response || 200
    patch:
      operationId: update-application
      summary: Active Directory Update Application
      description: Update the properties of an application registration.
      tags:
      - Applications
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationUpdate'
      responses:
        '204':
          description: Application updated successfully
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: Response || 204
    delete:
      operationId: delete-application
      summary: Active Directory Delete Application
      description: Delete an application registration from Microsoft Entra ID. The deleted application is soft-deleted (moved to the recycle bin) and can be restored within 30 days.
      tags:
      - Applications
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Application deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: Response || 204
components:
  schemas:
    ApplicationUpdate:
      type: object
      properties:
        displayName:
          type: string
        description:
          type: string
        signInAudience:
          type: string
        web:
          type: object
          properties:
            redirectUris:
              type: array
              items:
                type: string
    Application:
      type: object
      description: A Microsoft Entra application registration
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the application object (not the client ID)
        appId:
          type: string
          format: uuid
          description: The application (client) ID — used in OAuth2 flows
          example: 00000003-0000-0000-c000-000000000000
        displayName:
          type: string
          description: The display name for the application
          example: My Enterprise App
        description:
          type: string
          description: Free text description of the application
        signInAudience:
          type: string
          enum:
          - AzureADMyOrg
          - AzureADMultipleOrgs
          - AzureADandPersonalMicrosoftAccount
          - PersonalMicrosoftAccount
          description: Which Microsoft accounts are supported
          example: AzureADMyOrg
        identifierUris:
          type: array
          items:
            type: string
          description: URIs that identify the application within the tenant
        web:
          type: object
          description: Web platform configuration
          properties:
            redirectUris:
              type: array
              items:
                type: string
            implicitGrantSettings:
              type: object
              properties:
                enableAccessTokenIssuance:
                  type: boolean
                enableIdTokenIssuance:
                  type: boolean
            logoutUrl:
              type: string
        requiredResourceAccess:
          type: array
          items:
            type: object
            properties:
              resourceAppId:
                type: string
              resourceAccess:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                      enum:
                      - Role
                      - Scope
          description: API permissions required by the application
        keyCredentials:
          type: array
          items:
            type: object
            properties:
              keyId:
                type: string
              type:
                type: string
              usage:
                type: string
              displayName:
                type: string
              startDateTime:
                type: string
                format: date-time
              endDateTime:
                type: string
                format: date-time
          description: Certificate credentials (public key) for the application
        passwordCredentials:
          type: array
          items:
            type: object
            properties:
              keyId:
                type: string
              displayName:
                type: string
              startDateTime:
                type: string
                format: date-time
              endDateTime:
                type: string
                format: date-time
              hint:
                type: string
          description: Client secret credentials (metadata only — secret value returned only at creation)
        createdDateTime:
          type: string
          format: date-time
        deletedDateTime:
          type: string
          format: date-time
          nullable: true
    ApplicationCreate:
      type: object
      required:
      - displayName
      properties:
        displayName:
          type: string
        signInAudience:
          type: string
          default: AzureADMyOrg
        description:
          type: string
        web:
          type: object
          properties:
            redirectUris:
              type: array
              items:
                type: string
    ApplicationCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Application'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            Application.Read.All: Read all applications
            Application.ReadWrite.All: Read and write all applications
            Directory.Read.All: Read directory data
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            Application.Read.All: Read all applications
            Application.ReadWrite.All: Read and write all applications