MTN Group Organizations API

openapi: 3.2.0
info:
  title: Digital Identity Management Organizations API
  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
servers:
- url: https://serverRoot/tmf-api/digitalIdentityManagement/v4/
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Organizations
paths:
  /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
        description: Unique ID of the transaction.
        required: false
        schema:
          type: string
      - name: bearerToken
        description: Bearer token for Auth0 authentication
        required: true
        in: query
        schema:
          type: string
      - name: id
        in: path
        description: The ID of the organization.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Invitation created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/InvitationRespObject'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error405'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/InvitationReqObject'
        required: true
    get:
      tags:
      - Organizations
      summary: Get all invitations to organization
      description: Retrieves all invitations to an organization.
      parameters:
      - name: transactionId
        in: header
        description: Unique ID of the transaction.
        required: false
        schema:
          type: string
      - name: bearerToken
        description: Bearer token for Auth0 authentication
        required: true
        in: query
        schema:
          type: string
      - name: id
        in: path
        description: The ID of the organization.
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page index of the results to return. First page is 0.
        required: false
        schema:
          type: string
      - name: per_page
        in: query
        description: Number of results per page. Defaults to 50.
        required: false
        schema:
          type: string
      - name: totals
        in: query
        description: If true, the query response will include the total number of items that match the query.
        required: false
        schema:
          type: boolean
      - name: fields
        in: query
        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
        schema:
          type: string
      - name: include_fields
        in: query
        description: Whether the fields specified are to be included in the result, defaults to true.
        required: false
        schema:
          type: boolean
      - name: sort
        in: query
        description: The field to sort the results by.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/InvitationRespObject'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error405'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/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
        description: Unique ID of the transaction.
        required: false
        schema:
          type: string
      - name: bearerToken
        description: Bearer token for Auth0 authentication
        required: true
        in: query
        schema:
          type: string
      - name: id
        in: path
        description: The ID of the organization.
        required: true
        schema:
          type: string
      - name: invitationId
        in: path
        description: The invitation ID that needs to be deleted
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Invitation Deleted
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/SendInvitaionResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error405'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/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
        schema:
          type: string
      - name: userId
        in: path
        description: The ID of the user.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Roles successfully associated with user
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/SendInvitaionResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error405'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/RoleRequest'
        required: true
    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
        schema:
          type: string
      - name: userId
        in: path
        description: The ID of the user.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Roles successfully deleted from user
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/SendInvitaionResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error405'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/RoleRequest'
        required: true
components:
  schemas:
    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: '#/components/schemas/DPOMetadataObject'
    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
    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
    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:
                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: '#/components/schemas/InvitationObject'
    InvitationReqObject:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/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
    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
    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
    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: '#/components/schemas/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
    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
        statusCode:
          type: string
          description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
          example: '3001'
    InvitationReqAppMetadataObject:
      type: object
      allOf:
      - $ref: '#/components/schemas/MTNIDOrgAppMetadataObject'
    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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token