# Ref: https://spec.openapis.org/oas/v3.0.3

openapi: 3.0.1

info:
  title: Identity Service API

  version: '2020-09-01'

  description: |
    This is the specification of the HTTP API of the aziot-identityd service.

  license:
    name: 'MIT'

servers:
- url: 'http://identityd.sock/'
  description: |
    The server listens on a unix socket `/run/aziot/identityd.sock`


paths:
  /identities/identity?api-version=2020-09-01:
    get:
      tags:
      - Identity operations
      summary: Get primary cloud identity for authenticated workload (caller)
      operationId: getIdentity
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AziotIdentityResponse'
              examples:
                'Response for principals associated to device identities (SAS case)':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      auth:
                        type: 'sas'
                        keyHandle: 'string'
                'Response for principals associated to device identities (X.509 case)':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      auth:
                        type: 'x509'
                        keyHandle: 'string'
                        certId: 'string'
                'Response for principals associated to module identities (SAS case)':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'sas'
                        keyHandle: 'string'
                'Response for principals associated to module identities (X.509 case)':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'x509'
                        keyHandle: 'string'
                        certId: 'string'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /identities/device?api-version=2020-09-01:
    post:
      tags:
      - Identity operations
      summary: Get the IoT device provisioning result
      operationId: getDeviceIdentity
      x-codegen-request-body-name: GetDeviceIdentityRequest
      requestBody:
        description: The type of provisioned identity
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisioningResultRequest'
            example:
              value:
                type: 'aziot'
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                required: ['spec', 'type']
                type: object
                properties:
                  'type':
                    $ref: '#/components/schemas/AziotIdentityType'
                  'spec':
                    $ref: '#/components/schemas/AziotIdentitySpec'
              examples:
                'SAS case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      auth:
                        type: 'sas'
                        keyHandle: 'string'
                'X.509 case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      auth:
                        type: 'x509'
                        keyHandle: 'string'
                        certId: 'string'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /identities/modules?api-version=2020-09-01&type={type}:
    parameters:
    - $ref: '#/components/parameters/AziotIdentityTypeParameter'
    get:
      tags:
      - Identity operations
      summary: List IoT module identities
      operationId: getModuleIdentities
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AziotModuleIdentitiesResponse'
              examples:
                'SAS case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'sas'
                        keyHandle: 'string'
                'X.509 case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'x509'
                        keyHandle: 'string'
                        certId: 'string'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /identities/modules?api-version=2020-09-01:
    post:
      tags:
      - Identity operations
      summary: Create IoT module identity
      operationId: createModuleIdentity
      x-codegen-request-body-name: CreateModuleIdentityRequest
      requestBody:
        description: The type of module identity to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModuleRequest'
            examples:
              'Module identity':
                value:
                  type: 'aziot'
                  moduleId: 'module01'
              'Local identity':
                value:
                  type: 'local'
                  moduleId: 'module01'
                  localIdOpts:
                    type: 'x509'
                    attributes: 'server'
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleIdentityResponse'
              examples:
                'SAS case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'sas'
                        keyHandle: 'string'
                'X.509 case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'x509'
                        keyHandle: 'string'
                        certId: 'string'
                'Local identity':
                  value:
                    type: 'local'
                    spec:
                      moduleId: 'module01'
                      auth:
                        privateKey: 'private key bytes'
                        certificate: 'certificate bytes'
                        expiration: 'yyyy-mm-ddThh:mm:ss+00:00'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /identities/modules/{id}?api-version=2020-09-01&type={type}:
    parameters:
      - $ref: '#/components/parameters/IdentityName'
      - $ref: '#/components/parameters/ModuleIdentityKind'
    get:
      tags:
      - Identity operations
      summary: Get IoT module identity information
      operationId: getModuleIdentityById
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleIdentityResponse'
              examples:
                'SAS case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'sas'
                        keyHandle: 'string'
                'X.509 case':
                  value:
                    type: 'aziot'
                    spec:
                      hubName: 'myhub.net'
                      gatewayHost: 'parentdevice'
                      deviceId: 'device01'
                      moduleId: 'module01'
                      genId: '12345'
                      auth:
                        type: 'x509'
                        keyHandle: 'string'
                        certId: 'string'
                'Local identity':
                  value:
                    type: 'local'
                    spec:
                      moduleId: 'module01'
                      auth:
                        privateKey: 'private key bytes'
                        certificate: 'certificate bytes'
                        expiration: 'yyyy-mm-ddThh:mm:ss+00:00'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      tags:
      - Identity operations
      summary: Delete the IoT module identity
      operationId: deleteModuleIdentity
      responses:
        204:
          description: No Content
          content: {}
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /identities/device/reprovision?api-version=2020-09-01:
    post:
      tags:
      - Identity operations
      summary: Trigger an IoT device reprovisioning flow
      operationId: reprovision
      x-codegen-request-body-name: ReprovisionRequest
      requestBody:
        description: Type of identity to reprovision
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReprovisionRequest'
      responses:
        200:
          description: Ok
          content: {}
        204:
          description: No Content
          content: {}
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


components:
  schemas:
    AuthenticationCredentials:
      required:
      - type
      type: object
      properties:
        'type':
          type: string
          description: Indicates the type of authentication credential used.
          enum:
          - sas
          - x509
      discriminator:
        propertyName: type
        mapping:
          sas: '#/components/schemas/SASAuthenticationCredentials'
          x509: '#/components/schemas/X509AuthenticationCredentials'

    AziotIdentityResponse:
      required:
      - spec
      - type
      type: object
      properties:
        'type':
          $ref: '#/components/schemas/AziotIdentityType'
        'spec':
          $ref: '#/components/schemas/AziotIdentitySpec'

    AziotModuleIdentitiesResponse:
      type: object
      properties:
        'identities':
          type: array
          description: A collection of 'aziot' module identities
          items:
            $ref: '#/components/schemas/AziotModuleIdentityResponse'

    AziotIdentitySpec:
      required:
      - deviceId
      - gatewayHost
      - hubName
      type: object
      properties:
        'hubName':
          type: string
          description: The name of the IoT hub where the device is provisioned.
          example: myhub.net
        'gatewayHost':
          type: string
          description: The hostname of the parent Edge gateway that intermediates
            all requests for the current device when in a nested configuration. In
            a single-node deployment (i.e. non-nested) it will match the 'hubName'.
          example: parentdevice
        'deviceId':
          type: string
          description: The identity name of the provisioned device in the assigned
            IoT Hub.
          example: device01
        'moduleId':
          type: string
          description: The identity name of the device workload in the provisioned
            device in the assigned IoT Hub.
          example: module01
        'genId':
          type: string
          description: The generation ID of the device workload assigned by IoT Hub.
          example: "12345"
        'auth':
          $ref: '#/components/schemas/AuthenticationCredentials'
      description: The device identity specification.

    AziotIdentityType:
      type: string
      enum:
      - aziot
      example:
        aziot:
          value: aziot
          summary: 'Module identity.'

    AziotModuleIdentityResponse:
      required:
      - spec
      - type
      type: object
      properties:
        'type':
          $ref: '#/components/schemas/AziotIdentityType'
        'spec':
          $ref: '#/components/schemas/AziotModuleIdentitySpec'

    AziotModuleIdentitySpec:
      allOf:
      - $ref: '#/components/schemas/AziotIdentitySpec'
      required:
      - moduleId
      - genId
      type: object
      properties:
        'moduleId':
          type: string
          description: The identity name of the device workload in the provisioned
            device in the assigned IoT Hub.
          example: module01
        'genId':
          type: string
          description: The generation ID of the device workload assigned by IoT Hub.
          example: "12345"
      description: The module identity specification.

    CreateIdentityRequest:
      required:
      - moduleId
      - type
      type: object
      properties:
        'type':
          $ref: '#/components/schemas/IdentityKind'
        'moduleId':
          type: string
          description: Name of the module to add to the identity registry.
          example: module01

    CreateLocalIdentityRequest:
      allOf:
      - $ref: '#/components/schemas/CreateIdentityRequest'
      type: object
      properties:
        'localIdOpts':
          $ref: '#/components/schemas/LocalIdOptsType'

    CreateModuleRequest:
      oneOf:
      - $ref: '#/components/schemas/CreateIdentityRequest'
      - $ref: '#/components/schemas/CreateLocalIdentityRequest'
      discriminator:
        propertyName: type
        mapping:
          aziot: '#/components/schemas/CreateIdentityRequest'
          local: '#/components/schemas/CreateLocalIdentityRequest'

    ErrorResponse:
      required:
      - message
      type: object
      properties:
        'message':
          type: string

    IdentityKind:
      type: string
      description: The identity type.
      enum:
      - aziot
      - local
      example:
        aziot:
          value: aziot
          summary: 'Azure IoT Hub identity.'
        local:
          value: local
          summary: 'Local identity.'

    LocalIdentityResponse:
      required:
      - spec
      - type
      type: object
      properties:
        'type':
          $ref: '#/components/schemas/LocalIdentityType'
        'spec':
          $ref: '#/components/schemas/LocalIdentitySpec'

    LocalAuthType:
      required:
      - privateKey
      - certificate
      - expiration
      type: object
      properties:
        'privateKey':
          type: string
          format: byte
        'certificate':
          type: string
          format: byte
        'expiration':
          type: string
          format: date-time

    LocalIdentitySpec:
      required:
      - moduleId
      - auth
      type: object
      properties:
        'moduleId':
          type: string
          description: The identity name for the workload in the local registry.
          example: module01
        'auth':
          $ref: '#/components/schemas/LocalAuthType'
      description: The local identity specification.

    LocalIdentityType:
      type: string
      example: local
      enum:
      - local

    LocalIdOptsType:
      type: object
      properties:
        'type':
          type: string
          description: Type of local identity. Currently, only x509 is supported.
          enum:
          - x509
        'attributes':
          type: string
          description: Attributes of the X.509 local identity certificate. May be either client or server.
          enum:
          - client
          - server
      description: Optional field to specify configuration of the issued local identity.

    ModuleIdentityResponse:
      oneOf:
      - $ref: '#/components/schemas/AziotModuleIdentityResponse'
      - $ref: '#/components/schemas/LocalIdentityResponse'
      discriminator:
        propertyName: 'type'
        mapping:
          'aziot': '#/components/schemas/AziotModuleIdentityResponse'
          'local': '#/components/schemas/LocalIdentityResponse'

    ProvisioningResultRequest:
      required:
      - type
      type: object
      properties:
        'type':
          $ref: '#/components/schemas/AziotIdentityType'

    ReprovisionRequest:
      required:
      - type
      type: object
      properties:
        'type':
          type: string
          enum:
          - aziot

    SASAuthenticationCredentials:
      allOf:
      - $ref: '#/components/schemas/AuthenticationCredentials'
      required:
      - keyHandle
      type: object
      properties:
        'keyHandle':
          type: string
          description: Key handle used for Key Service requests.

    X509AuthenticationCredentials:
      allOf:
      - $ref: '#/components/schemas/AuthenticationCredentials'
      required:
      - certId
      - keyHandle
      type: object
      properties:
        'keyHandle':
          type: string
          description: Key handle used for Key Service requests.
        'certId':
          type: string
          description: Certificate ID of the identity X.509 certificate.


  parameters:
    AziotIdentityTypeParameter:
      name: type
      in: path
      description: Aziot identity type
      required: true
      schema:
        $ref: '#/components/schemas/AziotIdentityType'

    IdentityName:
      name: id
      in: path
      description: ID
      example: module01
      required: true
      schema:
        type: string

    ModuleIdentityKind:
      name: type
      in: path
      description: Supported identity types
      required: true
      schema:
        $ref: '#/components/schemas/IdentityKind'


