MTN TMF 720 - Digital Identity Management

swagger: '2.0'
info:
  title: Digital Identity Management
  description: |-
    ## TMF API Reference: TMF720 - Digital Identity Management

    Digital Identity Management API goal is to provide the ability to manage a digital identity. This digital identity allows to identify an individual, a resource, or a partyRole (a specific role - or set of roles - for a given individual). A digital identity is associated with credential/authentification method.
  version: 4.0.0
host: serverRoot
basePath: /tmf-api/digitalIdentityManagement/v4/
schemes:
  - https
consumes:
  - application/json;charset=utf-8
produces:
  - application/json;charset=utf-8
security:
  - ApiKeyAuth: []
  - OAuth2: []
  
securityDefinitions:
  ApiKeyAuth:
    type: "apiKey"
    name: "X-API-Key"
    in: "header"
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: https://api.mtn.com/v1/oauth/access_token
tags:
  - name: Users
  - name: Organizations
paths:
  /users/identity:
    get:
      operationId: Details of users identity
      summary: search users for their identity details
      description: This operation list or find DigitalIdentity entities
      tags:
        - Users
      parameters:
        - name: transactionId
          description: unique id for the transaction
          required: false
          in: header
          type: string
        - name: bearerToken
          description: Bearer token for Auth0 authentication
          required: true
          in: query
          type: string
        - name: assetId
          in: query
          description: Query string to search for users.
          required: false
          type: string
        - name: page
          in: query
          description: Page index of the results to return. First page is 0.
          required: false
          type: integer
        - name: perPage
          in: query
          description: Number of results per page. Defaults to 50.
          required: false
          type: integer
        - name: totals
          in: query
          description: If true, the query will return the total number of items that match.
          required: false
          type: boolean
        - name: sort
          in: query
          description: The field to use for sorting. Use `field:1` for ascending order and `field:-1` for descending order.
          required: false
          type: string
        - name: connection
          in: query
          description: The name of the connection to use for the search.
          required: false
          type: string
        - name: fields
          in: query
          description: A comma-separated list of fields to include or exclude from the result. Eg. "user_id,email,email_verified". Leave empty to retrieve all fields.
          required: false
          type: string
        - name: includeFields
          in: query
          description: Whether to include or exclude the fields specified in the `fields` parameter. Defaults to true.
          required: false
          type: boolean
        - name: searchEngine
          in: query
          description: The version of the search engine to use. Defaults to "v3".
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/userIdentityResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
  /update/users/{id}:
    patch:
      tags:
        - Users
      summary: Update a user
      description: Updates a user with the object's properties received in the request's body (the object should be a JSON object). These are the attributes that can be updated at the root
      parameters:
        - name: transactionId
          in: header
          type: string
          description: Unique identifier of the transaction.
          required: false
        - name: bearerToken
          description: Bearer token for Auth0 authentication
          required: true
          in: query
          type: string
        - name: id
          in: path
          description: The identifier of the user to update.
          type: string
          required: true
        - name: requestBody
          in: body
          schema:
            $ref: "#/definitions/UserReqObject"
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/userIdentityResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
  /users/{id}:
    get:
      tags:
        - Users
      summary: Get a user by Id
      description: Retrieve user details by specific user Id
      parameters:
        - name: transactionId
          in: header
          type: string
          description: Unique identifier of the transaction.
          required: false
        - name: bearerToken
          description: Bearer token for Auth0 authentication
          required: true
          in: query
          type: string
        - name: id
          in: path
          description: The identifier of the user whose details to be fetched.
          type: string
          required: true
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/getUserResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
  /organizations/{id}/invitations:
    post:
      tags:
        - Organizations
      summary: Create invitations to organization
      description: Creates an invitation for a user to join an organization.
      parameters:
        - name: transactionId
          in: header
          type: string
          description: Unique ID of the transaction.
          required: false
        - name: bearerToken
          description: Bearer token for Auth0 authentication
          required: true
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: The ID of the organization.
          required: true
        - name: requestBody
          in: body
          required: true
          schema:
            $ref: "#/definitions/InvitationReqObject"
      responses:
        "200":
          description: Invitation created
          schema:
            $ref: '#/definitions/InvitationRespObject'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
    get:
      tags:
        - Organizations
      summary: Get all invitations to organization
      description: Retrieves all invitations to an organization.
      parameters:
        - name: transactionId
          in: header
          type: string
          description: Unique ID of the transaction.
          required: false
        - name: bearerToken
          description: Bearer token for Auth0 authentication
          required: true
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: The ID of the organization.
          required: true
        - name: page
          in: query
          type: string
          description: Page index of the results to return. First page is 0.
          required: false
        - name: per_page
          type: string
          in: query
          description: Number of results per page. Defaults to 50.
          required: false
        - name: totals
          in: query
          description: If true, the query response will include the total number of items that match the query.
          required: false
          type: boolean
        - name: fields
          in: query
          type: string
          description: A comma-separated list of fields to include or exclude from the result (depending on the value of `include_fields`). Eg. "id,name". Leave empty to retrieve all fields.
          required: false
        - name: include_fields
          in: query
          description: Whether the fields specified are to be included in the result, defaults to true.
          required: false
          type: boolean
        - name: sort
          in: query
          description: The field to sort the results by.
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/InvitationRespObject'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
  /organizations/{id}/invitations/{invitationId}:
    delete:
      tags:
        - Organizations
      summary: Delete invitations by Invitation ID
      description: Delete invitations by Invitation ID
      parameters:
        - name: transactionId
          in: header
          type: string
          description: Unique ID of the transaction.
          required: false
        - name: bearerToken
          description: Bearer token for Auth0 authentication
          required: true
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: The ID of the organization.
          required: true
        - name: invitationId
          in: path
          type: string
          description: The invitation ID that needs to be deleted
          required: true
      responses:
        "200":
          description: Invitation Deleted
          schema:
            $ref: '#/definitions/SendInvitaionResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
  /organizations/{id}/members/roles/{userId}:
    post:
      summary: Assign one or more roles to a member of an organization
      tags:
        - Organizations
      description: This endpoint assigns one or more roles to a member of an organization. 
      parameters:
        - name: id
          in: path
          description: The ID of the organization.
          required: true
          type: string
        - name: userId
          in: path
          description: The ID of the user.
          required: true
          type: string
        - name: requestBody
          in: body
          required: true
          schema:
            $ref: "#/definitions/RoleRequest"
      responses:
        "200":
          description: Roles successfully associated with user
          schema:
            $ref: '#/definitions/SendInvitaionResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
    delete:
      summary: Remove one or more roles from a given user in the context of the provided organization
      tags:
        - Organizations
      description: This endpoint deletes one or more roles of a member in an organization.
      parameters:
        - name: id
          in: path
          description: The ID of the organization.
          required: true
          type: string
        - name: userId
          in: path
          description: The ID of the user.
          required: true
          type: string
        - name: requestBody
          in: body
          required: true
          schema:
            $ref: "#/definitions/RoleRequest"
      responses:
        "200":
          description: Roles successfully deleted from user
          schema:
            $ref: '#/definitions/SendInvitaionResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error405'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'

definitions:
  UserObject:
      type: object
      properties:
        email:
          type: string
          format: email
          description: The user's email address
          example: user@example.com
        emailVerified:
          type: boolean
          description: Whether the user's email address is verified
          example: true
        username:
          type: string
          description: The user's username
          example: user
        phoneNumber:
          type: string
          description: The user's phone number
          example: "+1234567890"
        phoneVerified:
          type: boolean
          description: Whether the user's phone number is verified
          example: false
        identities:
          type: array
          description: The user's identities
          items:
            type: object
            properties:
              userId:
                type: string
                description: The identity's user identifier
                example: "5f22f7f57f5d4b45c5c3292a"
              provider:
                type: string
                description: The identity's provider
                example: "auth0"
              connection:
                type: string
                description: The identity's connection
                example: "mtnid"
              isSocial:
                type: boolean
                description: Whether the identity is social
                example: false
        picture:
          type: string
          description: The URL of the user's picture
          example: "https://example.com/user-picture.jpg"
        name:
          type: string
          description: The user's name
          example: "John Doe"
        nickname:
          type: string
          description: The user's nickname
          example: "johnny"
        multifactor:
          type: array
          description: The types of multifactor authentication the user has enrolled in
          items:
            type: string
            example: "guardian"
        appMetadata:
          type: object
          description: Metadata associated with the user that impacts the user's core functionality and is editable by the application but not the user
        userMetadata:
          type: object
          description: Metadata associated with the user that does not impact the user's core functionality and is editable by the user
        blocked:
          type: boolean
          description: Whether the user is blocked
          example: false
        givenName:
          type: string
          description: The user's given name
          example: "John"
        familyName:
          type: string
          description: The user's family name
          example: "Doe"
  userIdentityResponse:
    type: object
    properties:
      statusCode:
        type: "integer"
        description: Status code from target system to indicate transaction status
      statusMessage:
        type: "string"
        description: Status message from target system to indicate transaction status.
      supportMessage:
        type: "string"
        description: Any additional message from backend
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
      data:
        type: object
        properties:
          users:
            type: array
            items:
              properties:
                appMetadata:
                  type: object
                  description: Metadata associated with the user that impacts the user's core functionality and is editable by the application but not the user
                  properties:
                    profile:
                      type: object
                      properties:
                        encodedUsername:
                          type: string
                          description: username in encoded format
                          example: "bWFraGlsMDA2QGdtYWlsLmNvbQ"
                        phoneVerified:
                          type: boolean
                          description: Whether the user's phone number is verified
                          example: "false"
                        profileType:
                          type: string
                          description: profile communication
                          example: "email_only"
                        unwantedPatterns:
                          type: boolean
                          description: any pattern identified
                          example: "false"
                        emailAlreadyExist: 
                          type: boolean
                          description: Checks if user email already exit in active directory
                          example: false
                    dpoMetadata:
                      type: object
                      allOf:
                        - $ref: '#/definitions/DPOMetadataObject'
  getUserResponse:
    type: object
    properties:
      statusCode:
        type: "integer"
        description: Status code from target system to indicate transaction status
      statusMessage:
        type: "string"
        description: Status message from target system to indicate transaction status.
      supportMessage:
        type: "string"
        description: Any additional message from backend
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
      data:
        type: object
        properties:
          user:
            type: object
            allOf:
              - $ref: '#/definitions/UserObject'
          userId:
            type: string
            description: The user's unique identifier
            example: auth0|5f22f7f57f5d4b45c5c3292a
          createdAt:
            type: string
            format: date-time
            description: When the user was created
            example: "2020-07-30T14:35:33.782Z"
          updatedAt:
            type: string
            format: date-time
            description: When the user was last updated
            example: "2020-07-30T14:35:33.782Z"
          lastIP:
            type: string
            description: The last IP address from which the user logged in
            example: "192.0.2.0"
          lastLogin:
            type: string
            format: date-time
            description: The last time the user logged in
            example: "2020-07-30T14:35:33.782Z"
          loginCount:
            type: integer
            description: The number of times the user has logged in
            example: 42
  DPOMetadataObject:
      type: object
      additionalProperties: false
      properties:
        services:
          type: array
          items:
            type: object
            properties:
              asset:
                type: string
                example: "partner"
              assetId:
                type: string
                description: Permanent or temporary Partner ID
                example: "23456"
              roles:
                type: array
                items:
                  type: string
                  example: "Admin"
              metadata:
                type: object
                properties:
                  tempId:
                    type: string
                    description: Temporary Partner ID
                    example: "56353"
                  status:
                    type: string
                    example: "Enabled"
                  termsAccepted:
                    type: boolean
                    description: Whether the terms have been accepted
                    example: false
  UserReqObject: # Currently on supporting DPO metadata updates
      type: object
      additionalProperties: false
      properties:
        appMetadata:
          type: object
          description: Metadata associated with the user that impacts the user's core functionality and is editable by the application but not the user
          properties:
            dpoMetadata:
              type: object
              allOf:
                - $ref: '#/definitions/DPOMetadataObject'
        clientId:
          type: string
          description: The ID of the client (application) for which the invitation is being sent.
  InvitationReqObject:
      additionalProperties: false
      allOf:
        - $ref: "#/definitions/InvitationObject"
        - type: object
          properties:
            sendInvitationEmail:
              type: boolean
              description: Whether the user will receive an invitation email (true) or no email (false), true by default
              example: true
            ttlSec:
              type: integer
              description: |
                Number of seconds for which the invitation is valid before expiration. If unspecified or set to 0, this value defaults to 604800 seconds (7 days). Max value: 2592000 seconds (30 days).
              example: 86400
            roles:
              type: array
              description: List of roles IDs to associated with the user.
              items:
                type: string
              example: ["rol_123"]
  InvitationObject:
      type: object
      properties:
        invitee:
          type: object
          description: The user being invited.
          properties:
            email:
              type: string
              format: email
              description: The email address of the user being invited.
        inviter:
          type: object
          description: The user sending the invitation.
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 300
              description: The name of the user sending the invitation.
        clientId:
          type: string
          description: The ID of the client (application) for which the invitation is being sent.
        connectionId:
          type: string
          description: The ID of the connection to use for the invitation.
        appMetadata:
          type: object
          description: Metadata associated with the user that impacts the user's core functionality and is editable by the application but not the user
          allOf:
            - $ref: "#/definitions/InvitationReqAppMetadataObject"
        userMetadata:
          type: object
          description: Metadata related to the user.
        ttlSec:
          type: integer
          description: |
            Number of seconds for which the invitation is valid before expiration. If unspecified or set to 0, this value defaults to 604800 seconds (7 days). Max value: 2592000 seconds (30 days).
          example: 86400
        roles:
          type: array
          description: List of roles IDs to associated with the user.
          items:
            type: string
          example: ["rol_123"]
        sendInvitationEmail:
          type: boolean
          description: Whether the user will receive an invitation email (true) or no email (false), true by default
          example: true
      required:
        - invitee
        - inviter
        - clientId
  InvitationReqAppMetadataObject:
    type: object
    allOf:
      - $ref: "#/definitions/MTNIDOrgAppMetadataObject"
  MTNIDOrgAppMetadataObject:
    type: object
    additionalProperties: false
    properties:
      "orgInvite":
        type: object
        properties:
          accountAlreadyExists:
            type: boolean
            description: true if "Search Users by Email" API returned a user and false if it did not
          profileUpdateRequired:
            type: boolean
            example: true
          profileUpdated:
            type: boolean
            example: false
          profile:
            type: object
            properties:
              givenName:
                type: string
                example: "given_name"
              familyName:
                type: string
                example: "family_name"
              name:
                type: string
                example: "name"
      dpoMetadata:
        type: object
        allOf:
          - $ref: '#/definitions/DPOMetadataObject'
  InvitationRespObject:
    type: object
    properties:
      statusCode:
        type: "integer"
        description: Status code from target system to indicate transaction status
      statusMessage:
        type: "string"
        description: Status message from target system to indicate transaction status.
      supportMessage:
        type: "string"
        description: Any additional message from backend
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
      data:
        type: array
        items:
          properties:
            id:
              type: string
              description: The ID of the invitation.
              example: "uinv_Z6a66ldcD64NmjMu"
            organizationId:
              type: string
              description: The ID of the organization.
            roles: ## For TCP
              type: array
              items:
                type: string
            invitationUrl:
              type: string
              description: The invitation url to be send to the invitee.
              format: strict-https-uri
              example: "https://app.mtn.com/login?invitation=XuVv8ywghwfX2hzl6cwLZncxI98lI2kV&organization={{AUTH0_ORG_ID}}&organization_name={{AUTH0_ORG_NAME}}"
            createdAt:
              type: string
              format: date-time
              description: The ISO 8601 formatted timestamp representing the creation time of the invitation.
            expiresAt:
              type: string
              format: date-time
              description: The ISO 8601 formatted timestamp representing the expiration time of the invitation.
            ticketId:
              type: string
              description: The id of the invitation ticket.
              example: "XuVv8ywghwfX2hzl6cwLZncxI98lI2kV"
            invitation:
              type: object
              allOf:
               - $ref: "#/definitions/InvitationObject"
  SendInvitaionResponse:
    properties:
      statusCode:
        type: "integer"
        description: Status code from target system to indicate transaction status
      statusMessage:
        type: "string"
        description: Status message from target system to indicate transaction status.
      supportMessage:
        type: "string"
        description: detail message from target system to indicate transaction status.
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
  RoleRequest:
    properties:
      roles:
        type: array
        items:
          type: string
          example: ["rol_123", "rol_456"]
       
  Error400:
    properties:
      statusCode:
        type: "integer"
        description: Status code from target system to indicate transaction status
      statusMessage:
        type: "string"
        description: Status message from target system to indicate transaction status.
      supportMessage:
        type: "string"
        description: detail message from target system to indicate transaction status.
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
  Error401:
    properties:
      error:
          type: "string"
          description: error message from target system to indicate transaction status.
          example: missing_authorization
      error_description:
          type: "string"
          description: detailed error message from target system to indicate transaction status.
          example: Missing Authorization header
  Error404:
    properties:
      status:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 404
      message:
        type: string
        description: details
        example: "no match found"
  Error405:
    properties:
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      status:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 405
      error:
          type: "string"
          description: error message
          example: Method Not Allowed
      message:
        type: string
        description: details
      path:
        type: string
        description: The path that caused the error
  Error415:
    properties:
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      status:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 415
      error:
          type: "string"
          description: error message
          example: Unsupported Media Type
      message:
        type: string
        description: details
      path:
        type: string
        description: The path that caused the error
  Error500:
    properties:
      statusMessage:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client
        example: 'Internal Server Error'
      st

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-tmf-720-digital-identity-management.yml