Mastercard Activity API

openapi: 3.2.0
info:
  title: Mastercard ID for Trust Providers Activity API
  description: Mastercard ID for Trust Providers is a service that helps businesses and organizations verify the identity of their customers. By utilizing advanced technology and security measures, Mastercard ID for Trust Providers enables businesses to securely authenticate the identities of individuals in real-time, reducing the risk of fraud and ensuring a seamless and secure customer experience. This service allows businesses to confidently verify the identities of their customers, streamlining operations and improving trust and security in online transactions. With Mastercard ID for Trust Providers, businesses can effectively combat fraud and identity theft, safeguarding sensitive information and enhancing the overall customer experience.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.1.0
servers:
- url: https://api.mastercard.com/idservice
  description: Production server (uses USA live data).
- url: https://sandbox.api.mastercard.com/idservice
  description: Sandbox server (testing USA environment).
- url: https://api.mastercard.com.au/idservice
  description: Production server  (uses AUS live data).
- url: https://sandbox.api.mastercard.com.au/idservice
  description: Sandbox server (testing AUS environment).
tags:
- name: Activity
paths:
  /rp-activity-searches:
    post:
      tags:
      - Activity
      responses:
        '200':
          $ref: '#/components/responses/RPActivitySearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: 'Retrieve decrypted RP activities and present them to the user in the TP

        app. Does not require a minimum authentication standard.

        **This API is mandatory.**

        '
      summary: View identity claim sharing activities which have occurred in a time period.
      operationId: searchRpActivity
      parameters:
      - $ref: '#/components/parameters/XUserIdentityParameter'
      - $ref: '#/components/parameters/XEncryptedPayload'
      requestBody:
        $ref: '#/components/requestBodies/RPActivitySearchRequest'
components:
  examples:
    EncryptedPayloadNoPDSExample:
      value:
        encryptedData: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyf
    RPActivitiesResponseExample:
      value:
        rpActivities:
        - rpName: Toys Inc
          consentType: OneTime
          createdDate: '2020-01-28T18:16:01.714Z'
          attributesConsented:
            passport.firstName: John
            passport.lastName: Doe
        rotatedPds: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given.
            Recoverable: false
    UserProfileDeletedErrorExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_DELETED
            Description: 'USER_PROFILE_DELETED: ID of the deleted profile.'
            Recoverable: false
            redirectUri: https://sample-rp-redirect-uri.com?error=server_error&state=AJahbadinvjbdvdnvljkdnvdfhsrbghrtiu4w
    ForbiddenExampleUnauthorizedScopedFields:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_SCOPED_FIELDS
            Description: 'UNAUTHORIZED_SCOPED_FIELDS: Requested scoped fields are not part of whitelisted fields.'
            Recoverable: false
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request.
            Recoverable: false
    NotFoundExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_ID_NOT_FOUND
            Description: The provided user profile ID does not exist.
            Recoverable: false
  schemas:
    ErrorResponse:
      required:
      - Errors
      type: object
      description: The error response model used by all the API endpoints.
      properties:
        Errors:
          required:
          - Error
          type: object
          description: The error response model used by all the API endpoints.
          properties:
            Error:
              type: array
              description: A list of Error objects.
              minItems: 1
              items:
                type: object
                properties:
                  Source:
                    type: string
                    description: The source of the problem. That is where the error occurred.
                    example: mids
                  ReasonCode:
                    type: string
                    description: A code defining the error, as defined in documentation.
                    example: USER_PROFILE_ID_NOT_FOUND
                  Description:
                    type: string
                    description: A description of this specific occurrence of the Reason code.
                    example: The provided user profile ID does not exist.
                  Recoverable:
                    type: boolean
                    description: Whether or not retrying this request could result in a successful response.
                    example: false
                  Details:
                    type: string
                    description: More details of this specific error. This is an optional field and is sometimes used to give a more comprehensive description of the error that has occurred, when required.
                    example: User X was not found
                  redirectUri:
                    type: string
                    description: TP will use this URI to redirect to RP.
                    pattern: ^(https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|www\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9]+\.[^\s]{2,}|www\.[a-zA-Z0-9]+\.[^\s]{2,})$
                    example: https://sample-rp-redirect-uri.com/?error=invalid_scope&state=AJahbadinvjbdvdnvljkdnvdfhsrbghrtiu4w&ARID=1234&error_description=claim_not_satisfied
    PDS:
      type: string
      description: Encrypted Personal Device Storage (PDS) which hosts the users identity attributes. The PDS can be retrieved from the MIDS Core SDK, please refer to the SDK guide for details on how to retrieve this.
      pattern: ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$
      minLength: 1
      example: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    RPActivities:
      required:
      - rpActivities
      properties:
        rpActivities:
          type: array
          description: Relying Party activity items.
          items:
            $ref: '#/components/schemas/RPActivityItems'
        rotatedPds:
          type: string
          description: A rotated PDS is created and returned when the encryption key expires and a new key is generated.
          pattern: ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$
          minLength: 1
          example: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    UserConsent:
      enum:
      - ACCEPT
      - DECLINE
      - REVOKE
      - EXPIRE
      type: string
      description: Confirmation provided by the TP that the user has consented that the ID-Network can have access to their identity for the purposes of the API call. Should be ACCEPT, a forbidden exception will be thrown if it is any other value.
      pattern: ^(ACCEPT|DECLINE|REVOKE|EXPIRE)$
      minLength: 6
      maxLength: 7
      example: ACCEPT
    RPActivitySearch:
      required:
      - pds
      - startIndex
      - endIndex
      - userConsent
      type: object
      properties:
        pds:
          $ref: '#/components/schemas/PDS'
        startIndex:
          type: integer
          description: Start index of the RP activity.
          format: int32
          minimum: 1
          maximum: 999
          example: 3
        endIndex:
          type: integer
          description: End index of the RP activity.
          format: int32
          minimum: 1
          maximum: 999
          example: 10
        userConsent:
          $ref: '#/components/schemas/UserConsent'
        sdkVersion:
          $ref: '#/components/schemas/SdkVersion'
    RPActivityItems:
      required:
      - rpName
      - consentType
      - createdDate
      - attributesConsented
      type: object
      properties:
        rpName:
          type: string
          description: Relying Party name.
          minLength: 1
          maxLength: 255
          example: Toys inc
        consentType:
          type: string
          description: User consent type.
          minLength: 1
          maxLength: 10
          example: OneTime
        createdDate:
          type: string
          description: Date of the event.
          minLength: 1
          maxLength: 29
          example: '2020-01-28T13:16:01.714-05:00'
        attributesConsented:
          type: object
          description: This is the same data structure that is returned to Relying Party.
          additionalProperties: {}
          example:
            passport.firstName: John
            passport.lastName: Doe
    SdkVersion:
      type: string
      description: Mastercard SDK version integrated with TP App, it is a constant extracted from MIDS SDK Configurations (generated while bundling SDK artifacts). If the TP app supports split PDS, this attribute MUST be specified.
      pattern: ^[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}$
      minLength: 5
      maxLength: 255
      example: 2.3.0
  responses:
    NotFoundError:
      description: The request didn't match an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UserProfileDeletedErrorExample:
              $ref: '#/components/examples/UserProfileDeletedErrorExample'
    RPActivitySearchResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          schema:
            type: string
          description: A random 128-bit UUID represents the transaction.
        X-User-Identity:
          schema:
            type: string
          description: JWT token for session validation in subsequent API calls.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RPActivities'
          examples:
            UnencryptedResponseExample:
              $ref: '#/components/examples/RPActivitiesResponseExample'
            EncryptedResponseExample:
              $ref: '#/components/examples/EncryptedPayloadNoPDSExample'
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
            ForbiddenExampleUnauthorizedScopedFields:
              $ref: '#/components/examples/ForbiddenExampleUnauthorizedScopedFields'
  parameters:
    XUserIdentityParameter:
      in: header
      name: X-User-Identity
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
      description: 'JWT token for session validation. Returned as response header in previous API calls with key X-User-Identity.

        '
      schema:
        type: string
    XEncryptedPayload:
      in: header
      name: X-Encrypted-Payload
      type: boolean
      description: 'An indicator that the request is encrypted or indicates that the client is able to receive an encrypted response. If not set, the payload will be treated as plaintext.

        '
      example: true
      schema: null
  requestBodies:
    RPActivitySearchRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RPActivitySearch'
      required: true