Mastercard Scopes API

openapi: 3.2.0
info:
  title: Mastercard Scopes API
  contact:
    name: API Support
    url: https://developer.mastercard.com/support
    email: apisupport@mastercard.com
  version: '1.0'
  description: 'Operations tagged Scopes across 2 of this provider''s published API definitions: mastercard-id-for-identity-providers-openapi.yml, mastercard-id-for-trust-providers-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mastercard.com.au/idservice-idp
  description: Production server (uses live data).
- url: https://sandbox.api.mastercard.com.au/idservice-idp
  description: Sandbox server (testing environment).
- 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: Scopes
paths:
  /scopes/{arid}:
    get:
      summary: To retrieve the scopes and RP details associated with the arid. The ARID must be in PENDING status.
      tags:
      - Scopes
      responses:
        '200':
          $ref: '#/components/responses/RPScopesSuccessResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: "To retrieve the requested scopes and RP details associated with the ARID.   \n**This API is mandatory.**\n"
      operationId: retrieveRPScopes
      parameters:
      - $ref: '#/components/parameters/AridParameter'
    servers:
    - url: https://api.mastercard.com.au/idservice-idp
      description: Production server (uses live data).
    - url: https://sandbox.api.mastercard.com.au/idservice-idp
      description: Sandbox server (testing environment).
  /scope-fulfillments/{arid}:
    put:
      parameters:
      - $ref: '#/components/parameters/AridParameter'
      - $ref: '#/components/parameters/XEncryptedPayload'
      tags:
      - Scopes
      responses:
        '200':
          $ref: '#/components/responses/ScopeFulfillmentResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: "Process claims data  provided by the IDP for the corresponding RP authentication.   \nRequest scopes and update the authentication request.   \n **This API is mandatory.**\n"
      summary: To process the IDP claims and update the authentication request with the claims data. The Relying party can get these claims data via RP claim sharing endpoint.
      operationId: ProcessClaimsRequestedScopes
      requestBody:
        $ref: '#/components/requestBodies/ScopeFulfillmentRequest'
    servers:
    - url: https://api.mastercard.com.au/idservice-idp
      description: Production server (uses live data).
    - url: https://sandbox.api.mastercard.com.au/idservice-idp
      description: Sandbox server (testing environment).
  /claims/scopes/{arid}:
    get:
      summary: Share an Identity with an External RP - Retrieve details of the scope request being made by an RP.
      tags:
      - Scopes
      responses:
        '200':
          $ref: '#/components/responses/RPScopesSuccessResponse_2'
        '400':
          $ref: '#/components/responses/BadRequestError_2'
        '401':
          $ref: '#/components/responses/UnauthorizedError_2'
        '404':
          $ref: '#/components/responses/NotFoundError_2'
      description: "Used to retrieve the scopes and RP details associated with the ARID. Does not require a minimum authentication standard.   \n**This API is mandatory.**\n"
      operationId: retrieveCSScopes
      parameters:
      - $ref: '#/components/parameters/AridParameter_2'
    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).
components:
  examples:
    EncryptedPayloadNoPDSExample:
      value:
        encryptedData: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyf
    BadRequestInvalidFormatExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: BAD_REQUEST
            Description: Claims in the request are empty.
            Recoverable: false
            Details: Invalid Date format. Valid format expected is 'YYYY-MM-DD'
    BadRequestInvalidClaimsExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: INVALID_CLAIMS
            Description: Provided claims are invalid.
            Recoverable: false
            Details: Claims are invalid. System defined claims for a mandatory scope 'ageOver' can't be empty
    IDPScopesAuthorizationRequestExample:
      value:
        claims:
        - claim: address:0:250
          values:
          - name: address
            value: 2102 North Square Blvd
        - claim: govtId:0:100
          values:
          - name: firstName
            value: abc
          - name: lastName
            value: xyz
          - name: dateOfBirth
            value: '1990-12-12'
        userConsent: ACCEPT
        locale: en-US
        countryCode: US
    BadRequestClaimsEmptyExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: BAD_REQUEST
            Description: Claims in the request are empty.
            Recoverable: false
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request.
            Recoverable: false
    IDPScopesAuthorizationDataResponseExample:
      value:
        redirectUri: http://rp.com/auth?code=xcxxzaas3&state=xccx234
    NotFoundExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CLAIM_SHARING_ARID_DOES_NOT_EXIST
            Description: ARID does not exist.
            Recoverable: false
    NotFoundExample_2:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_ID_NOT_FOUND
            Description: The provided user profile ID does not exist.
            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
  schemas:
    RPScopes:
      required:
      - scopes
      - rpName
      - rpLogoUrl
      type: object
      properties:
        scopes:
          type: array
          items:
            type: string
            example: name:0:365
            description: The list of scopes that have been requested.
        rpName:
          type: string
          minLength: 1
          maxLength: 255
          example: THISRP
          description: RP Name
          pattern: ^[a-zA-Z\s ,.'-]{1,255}$
        rpLogoUrl:
          type: string
          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,})$
          description: The URL of the logo of the RP.
          example: https://www.rpsite.com/logo.jpg
    IDPScopesAuthorization:
      required:
      - claims
      - userConsent
      type: object
      properties:
        claims:
          description: Claims for RP requested scopes.
          type: array
          items:
            $ref: '#/components/schemas/IDPClaim'
          example:
          - claim: address:0:250
            values:
            - name: address
              value: 2102 North Square Blvd
          - claim: govtId:0:100
            values:
            - name: firstName
              value: abc
            - name: lastName
              value: xyz
            - name: dateOfBirth
              value: '1990-12-12'
          minItems: 1
        userConsent:
          maxLength: 8
          minLength: 6
          enum:
          - ACCEPT
          - DECLINE
          - REVOKE
          - EXPIRE
          type: string
          example: ACCEPT
          description: Attribute used to signify the user consent. If consent is other than 'ACCEPT' redirect url will be provided with the error details.
        locale:
          type: string
          example: en-US
          pattern: ^[a-z]{2}-[a-zA-Z]{2}$
          description: 'IETF BCP 47 Format E.g. "en-GB" (English - United Kingdom), "es-MX" (Spanish - Mexico). More information: Locale ID (LCID) as defined by Microsoft. Not required. The default value is "en-US".'
        countryCode:
          description: ISO-3166 Alpha-2 standard.
          type: string
          example: US
          pattern: ^[a-zA-Z]{2}$
    ApiError:
      type: object
      properties:
        Source:
          type: string
          description: Source of where the error occurred.
          minLength: 3
          maxLength: 50
          example: mids
        ReasonCode:
          type: string
          description: Code of the error.
          minLength: 5
          maxLength: 100
          example: BAD_REQUEST
        Description:
          type: string
          description: The cause of the error.
          minLength: 10
          maxLength: 250
          example: Claims in the request are empty
        Recoverable:
          type: boolean
          description: Indicates if the error can be recovered from.
          example: false
        Details:
          type: string
          description: Contains information about the error.
          minLength: 10
          maxLength: 1000
          example: IOException Occurred
    IDPClaim:
      required:
      - claim
      - values
      type: object
      properties:
        claim:
          maxLength: 255
          minLength: 1
          description: A unique claim name particular to a scope requested by the relying party.
          type: string
          example: address:0:250
        values:
          type: array
          items:
            $ref: '#/components/schemas/IDPIndividualClaim'
          description: List of values particular to a scope requested by the relying party.
          minItems: 1
    ApiErrors:
      description: List of errors.
      example:
        $ref: '#/components/examples/NotFoundExample'
      required:
      - Error
      type: object
      properties:
        Error:
          $ref: '#/components/schemas/ApiErrorList'
    ApiErrorWrapper:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/ApiErrors'
    ApiErrorList:
      description: Error Details.
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/ApiError'
    IDPIndividualClaim:
      required:
      - name
      - value
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 1
          description: A single claim name.
          type: string
          example: address
        value:
          maxLength: 255
          minLength: 1
          description: The claim value.
          type: string
          example: 2102 North Square Blvd.
    IDPScopesAuthorizationData:
      required:
      - redirectUri
      type: object
      properties:
        redirectUri:
          description: URL where IDP would redirect authorization response to be consumed by relying party
          type: string
          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: http://rp.com/auth?code=xcxxzaas3&state=xccx234
    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
    RPScopes_2:
      required:
      - scopes
      - rpName
      - rpLogoUrl
      type: object
      properties:
        scopes:
          type: array
          items:
            type: string
            description: The list of scopes that have been requested.
            example: name:0:365
        rpName:
          type: string
          description: RP Name.
          minLength: 1
          maxLength: 255
          example: THISRP
        rpLogoUrl:
          type: string
          description: The URL of the logo of the RP.
          minLength: 1
          example: https://www.rpsite.com/logo.jpg
  headers:
    X-Transaction-ID:
      schema:
        type: string
      description: A random 128-bit UUID represents the transaction.
  responses:
    NotFoundError:
      description: The target resource has not been found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorWrapper'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    BadRequestError:
      description: The server cannot process the request due to bad request. client should consider correcting the request before retrying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorWrapper'
          examples:
            BadRequestClaimsEmptyExample:
              $ref: '#/components/examples/BadRequestClaimsEmptyExample'
            BadRequestInvalidFormatExample:
              $ref: '#/components/examples/BadRequestInvalidFormatExample'
            BadRequestInvalidClaimsExample:
              $ref: '#/components/examples/BadRequestInvalidClaimsExample'
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    ScopeFulfillmentResponse:
      description: Success response.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IDPScopesAuthorizationData'
          examples:
            ScopeFulfillmentResponseUnencryptedExample:
              $ref: '#/components/examples/IDPScopesAuthorizationDataResponseExample'
            ScopeFulfillmentResponseEncryptedExample:
              $ref: '#/components/examples/EncryptedPayloadNoPDSExample'
    RPScopesSuccessResponse:
      description: Success response.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RPScopes'
    RPScopesSuccessResponse_2:
      description: Success
      headers:
        X-Transaction-ID:
          schema:
            type: string
          description: A random 128-bit UUID represents the transaction.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RPScopes_2'
    NotFoundError_2:
      description: The request didn't match an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample_2'
    BadRequestError_2:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UserProfileDeletedErrorExample:
              $ref: '#/components/examples/UserProfileDeletedErrorExample'
    UnauthorizedError_2:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
  parameters:
    XEncryptedPayload:
      in: header
      name: X-Encrypted-Payload
      example: true
      description: 'Indicator that request is encrypted or to indicate that client is able to receive a encrypted response. If not set, payload will treated as plaintext.

        '
      schema:
        type: boolean
    AridParameter:
      name: arid
      in: path
      description: UUID represents the ARID.
      example: df52649e-4096-456a-bca0-751ee470009f
      required: true
      schema:
        maxLength: 36
        minLength: 36
        type: string
        pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
    AridParameter_2:
      name: arid
      in: path
      description: A unique identifier for any activity being executed arising out of a Claim Share request. This value is passed as a parameter in the URL redirecting a User to the TP Flow during a Claim Share. .
      example: df52649e-4096-456a-bca0-751ee470009f
      required: true
      schema:
        type: string
        pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
        maxLength: 36
        minLength: 36
  requestBodies:
    ScopeFulfillmentRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IDPScopesAuthorization'
          examples:
            ScopeFulfillmentRequestUnencryptedExample:
              $ref: '#/components/examples/IDPScopesAuthorizationRequestExample'
            ScopeFulfillmentRequestEncryptedExample:
              $ref: '#/components/examples/EncryptedPayloadNoPDSExample'
      required: true
x-refined-from:
- mastercard-id-for-identity-providers-openapi.yml
- mastercard-id-for-trust-providers-openapi.yml