Barclays User Identity Context API

openapi: 3.2.0
info:
  title: Authentication User Identity Context API
  description: Secure login for Barclays credit card customers to access online services
  version: '2.0'
tags:
- name: user-identity-context
  description: User identity context API
paths:
  /users/{externalAccountId}/context:
    summary: user identity context for customer login. This operation contains sensitive data in request and response payload.
    description: The API provides the context URL for customer login via IDP.
    post:
      tags:
      - user-identity-context
      summary: To setup user identity context for customer login.
      description: The API provides the context URL for customer login via IDP. Uses `client_credentials` token.
      operationId: request-auth
      parameters:
      - name: Correlation-ID
        in: header
        description: "Unique end-to-end trace ID. The initiating system (such as a Channel or \nBatch Job), must generate this unique ID, then this must be passed \nthrough the API call stack. This is required to maintain compliance with the current Barclays REST Standard."
        required: true
        deprecated: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          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}$
        example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      - name: Content-Type
        in: header
        description: Content-Type
        required: true
        deprecated: false
        schema:
          type: string
        example: application/json
      - name: externalAccountId
        in: path
        description: External Account ID (UUID format)
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 1
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        example: 2c4717c4-e2f3-4071-2b86-b86890876322
      requestBody:
        description: User identity context request. Payload fully encrypted.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserIdentityContextRequest'
            examples:
              UserIdentityContextRequest:
                $ref: '#/components/examples/user-identity-context-request'
      responses:
        '200':
          $ref: '#/components/responses/UserIdentityContextResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      deprecated: false
components:
  examples:
    example-error-400-bad-request:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: BAD_REQUEST
          title: The request is invalid or not properly formed.
    example-error-403:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: ACCESS_FORBIDDEN
          title: The user is not permitted to access the requested operation and it cannot be completed.
    example-error-500:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error.
    example-error-404:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: RESOURCE_NOT_FOUND
          title: The requested operation failed because a resource associated with the request could not be found.
    example-error-401:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: AUTHENTICATION_ERROR
          title: The user could not be authenticated for this request.
    user-identity-context-request:
      value:
        data:
          product: SMG
          channel: MOBILE
          fraudSessionId: 6c9b83bc-5c94-45c8-a594-5ea890409b62
          applicationId: 1346780132564
          customerProfileDetails:
            memberNumber: CM12345
            firstName: John
            lastName: Doe
            email: john.doe@abc.com
            numberOfAssociatedDevices: 3
            digitalWalletLastLoginDate: 1734260400000
            additionalAttributes:
            - name: attribute_1
              value: value_1
              type: text
            - name: attribute_2
              value: value_2
              type: text
          deviceDetails:
            deviceType: PHONE
            deviceModel: SM-S928U
            deviceOSVersion: '35'
            deviceFingerprintType: THREATMETRIX
            deviceFingerprintId: 123e4567-e89b-12d3-a456-42661417400
            deviceRegistrationDate: 1734260400000
            deviceLastUsedDate: 1734260400000
            deviceLockPresent: true
            deviceBiometricType: FINGER
            serviceCarrierName: T-Mobile
            sim1PhoneNumber: 555-555-5555
            sim2PhoneNumber: 555555-5551
            deviceIPAddress: 111.111.1.1
            dateCurrentSimLinkedToDevice: 1734260400000
            additionalAttributes:
            - name: attribute_1
              value: value-1
              type: text
            - name: attribute_2
              value: value-2
              type: text
    user-identity-context-response:
      value:
        data:
          expiry: 30
          resumeUrl: https://baclays-authoriation-host/to-be-opened-in-web-view/payload-response-fully-encrypted?client_id=bdn_abc
    example-error-503:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
  schemas:
    ErrorResponseType:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'An API error response.

        '
      properties:
        errors:
          type: array
          description: 'Contains one or more error messages and is mutually exclusive with the data item.

            This will not be returned in success scenarios.

            '
          items:
            $ref: '#/components/schemas/ErrorType'
          maxItems: 50
          minItems: 0
      nullable: false
    UserIdentityContextResponse:
      type: object
      additionalProperties: false
      deprecated: false
      description: User identify context response.
      properties:
        data:
          $ref: '#/components/schemas/UserIdentityContextResponseData'
      required:
      - data
      nullable: false
    DeviceAttributes:
      type: array
      description: Additional device attributes useful for fraud risk assessment
      items:
        $ref: '#/components/schemas/NameValueAttributePair'
      maxItems: 100
      minItems: 0
      nullable: true
    NameValueAttributePair:
      type: object
      additionalProperties: false
      deprecated: false
      description: Attribute name and value pair
      properties:
        name:
          type: string
          description: Attribute name
          example: name
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_]{1,100}$
        value:
          type: string
          description: Attribute value
          example: partner-details
          maxLength: 200
          minLength: 1
          pattern: ^[a-zA-Z0-9_\-\s\@\#\$\&\*\(\)\+\=\"\.\,\/]{1,200}$
        type:
          type: string
          default: text
          description: Attribute data type
          enum:
          - text
          - number
          - boolean
          - iso_date
          example: text
      required:
      - name
      - value
      nullable: false
    ErrorType:
      type: object
      additionalProperties: false
      description: Message details - additional operation execution information.
      properties:
        id:
          type: string
          description: Generated message identifier for particular request, helping to locate server logs.
          example: 9709-4675-2456-7801
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9\-]{1,50}$
        code:
          type: string
          description: Machine readable, unique code of the message related to particular case within operation execution.
          example: ACCOUNT_NUMBER_NOT_FOUND
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_]{1,100}$
        title:
          type: string
          description: Short description of the error. Not for displaying purposes.
          example: The authorization credentials required for this request are invalid.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,.']{1,250}$
        detail:
          type: string
          description: Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,.']{1,250}$
      required:
      - code
      - id
      - title
    UserIdentityContextRequestData:
      type: object
      additionalProperties: false
      deprecated: false
      description: User identity context request data.
      properties:
        product:
          type: string
          description: Product/CPC for the IDP.
          example: SMG
          maxLength: 20
          minLength: 3
          pattern: ^[A-Za-z0-9]{3,20}$
        channel:
          type: string
          description: Channel field for the IDP page rendering.
          enum:
          - WEB
          - MOBILE
          example: MOBILE
        fraudSessionId:
          type: string
          description: Applicant Fraud Session ID.
          example: 6c9b83bc-5c94-45c8-a594-5ea890409b62
          maxLength: 36
          minLength: 36
          pattern: ^[a-fA-F0-9]{8}-([a-fA-F0-9]{4}-){3}[a-fA-F0-9]{12}$
        applicationId:
          type: number
          description: Applicant Application ID.
          example: 1346780132564
          pattern: ^[0-9]{15,16}$
        customerProfileDetails:
          $ref: '#/components/schemas/CustomerProfile'
        deviceDetails:
          $ref: '#/components/schemas/DeviceDetails'
      required:
      - channel
      - customerProfileDetails
      - deviceDetails
      - product
      nullable: false
    DeviceDetails:
      type: object
      additionalProperties: false
      deprecated: false
      description: Customer details
      properties:
        deviceType:
          type: string
          enum:
          - PHONE
          - TABLET
          - LAPTOP
        deviceModel:
          type: string
          example: SM-S928U
          maxLength: 25
          minLength: 1
          pattern: ^[a-zA-Z0-9-]{1,25}$
        deviceOS:
          type: string
          example: Android
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9-]{1,50}$
        deviceOSVersion:
          type: string
          example: '35'
          maxLength: 20
          minLength: 1
          pattern: ^[a-zA-Z0-9.\-]{1,20}$
        deviceFingerprintType:
          type: string
          description: Device fingerprint type
          enum:
          - THREATMETRIX
          - CUSTOM
          example: THREATMETRIX
        deviceFingerprintId:
          type: string
          format: uuid
          description: Unique identifier for device fingerprint
          example: 123e4567-e89b-12d3-a456-426614174000
          maxLength: 36
          minLength: 36
          pattern: ^[a-fA-F0-9]{8}-([a-fA-F0-9]{4}-){3}[a-fA-F0-9]{12}$
        deviceRegistrationDate:
          type: integer
          format: int64
          description: Device registration date in Unix timestamp (milliseconds since epoch)
          example: 1734260400000
          maximum: 253402300799999
          minimum: 0
        deviceLastUsedDate:
          type: integer
          format: int64
          description: Device last used date in Unix timestamp (milliseconds since epoch)
          example: 1734260400000
          maximum: 253402300799999
          minimum: 0
        deviceLockPresent:
          type: string
          description: Indicates whether device lock is present
          enum:
          - Y
          - N
          example: Y
          nullable: true
        deviceBiometricType:
          type: string
          enum:
          - FINGER
          - PIN
          - IRIS
          - FACE
          nullable: true
        serviceCarrierName:
          type: string
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9&-]{1,50}$
          nullable: true
        deviceIPAddress:
          type: string
          description: Client IP address (IPv4 or IPv6)
          example: 111.111.1.1
          maxLength: 45
          minLength: 7
          pattern: ^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)|([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$
          nullable: true
        deviceSim1PhoneNumber:
          type: string
          description: Phone number associated with device SIM
          example: '8882223333'
          maxLength: 40
          minLength: 6
          pattern: ^[0-9\- ]{6,40}$
          nullable: true
        deviceSim2PhoneNumber:
          type: string
          description: Phone number associated with second SIM for dual-SIM devices
          example: '8882223333'
          maxLength: 40
          minLength: 6
          pattern: ^[0-9\- ]{6,40}$
          nullable: true
        dateCurrentSimLinkedToDevice:
          type: integer
          format: int64
          description: Date current SIM linked to device in Unix timestamp (milliseconds since epoch)
          example: 1734260400000
          maximum: 253402300799999
          minimum: 0
        additionalAttributes:
          $ref: '#/components/schemas/DeviceAttributes'
      nullable: true
    UserIdentityContextResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: User identity context response data.
      properties:
        expiry:
          type: integer
          description: Resume URL expiry in seconds.
          example: 10
          maximum: 60
          minimum: 1
        resumeUrl:
          type: string
          description: Redirect URL to continue with Login or IDP resume.
          example: https://oauth-sit.tiaa.barclaysus.com/sp/AA8XC0009543FDWWWPI/as/authorization.oauth2
          maxLength: 300
          minLength: 1
          pattern: ^(?=.{1,300}$)https:\/\/[^\s/$.?#].[^\s]*$
          nullable: true
      nullable: false
    CustomerProfileAttributes:
      type: array
      description: Additional customer profile attributes useful for fraud risk assessment
      items:
        $ref: '#/components/schemas/NameValueAttributePair'
      maxItems: 100
      minItems: 0
      nullable: true
    UserIdentityContextRequest:
      type: object
      additionalProperties: false
      deprecated: false
      description: User identity context request.
      properties:
        data:
          $ref: '#/components/schemas/UserIdentityContextRequestData'
      required:
      - data
      nullable: false
    CustomerProfile:
      type: object
      additionalProperties: false
      deprecated: false
      description: Customer's partner account relationship details
      properties:
        memberNumber:
          type: string
          example: CM12345
          maxLength: 17
          minLength: 1
          pattern: ^[a-zA-Z0-9]{1,17}$
        firstName:
          type: string
          description: Customer's first name on partner account
          example: John
          maxLength: 32
          minLength: 2
          pattern: ^[-a-zA-Z'\s]{2,32}$
        lastName:
          type: string
          description: Customer's last name on partner account
          example: Doe
          maxLength: 32
          minLength: 2
          pattern: ^[-a-zA-Z'\s]{2,32}$
        email:
          type: string
          description: Customer's email on partner account
          example: support@barclays.com
          maxLength: 320
          minLength: 6
          pattern: ^(?=.{1,256}$)^([a-zA-Z0-9.\x21#$\x25&'\x2A\x2B\/=\x3F\x5E_`\x7E-]{1,64})@(([a-zA-Z0-9-]{1,180}(\.[a-zA-Z0-9-]{1,62}){1,9}))$
        nameChangeTimestamp:
          type: integer
          format: int64
          description: Timestamp of customer name change in Unix timestamp (milliseconds since epoch)
          example: 1734260400000
          maximum: 253402300799999
          minimum: 0
        previousFirstName:
          type: string
          description: Customer's first name on partner account before last change
          example: John
          maxLength: 32
          minLength: 2
          pattern: ^[-a-zA-Z'\s]{2,32}$
        previousLastName:
          type: string
          description: Customer's last name on partner account before last change
          example: Doe
          maxLength: 32
          minLength: 2
          pattern: ^[-a-zA-Z'\s]{2,32}$
        emailChangeTimestamp:
          type: integer
          format: int64
          description: Timestamp of customer email change in Unix timestamp (milliseconds since epoch)
          example: 1734260400000
          maximum: 253402300799999
          minimum: 0
        previousEmail:
          type: string
          description: Customer's email on partner account before last change
          example: support@barclaycardus.com
          maxLength: 320
          minLength: 6
          pattern: ^(?=.{1,256}$)^([a-zA-Z0-9.\x21#$\x25&'\x2A\x2B\/=\x3F\x5E_`\x7E-]{1,64})@(([a-zA-Z0-9-]{1,180}(\.[a-zA-Z0-9-]{1,62}){1,9}))$
        numberOfAssociatedDevices:
          type: integer
          format: int32
          description: Number of devices associated with the account
          example: 3
          maximum: 100
          minimum: 0
        digitalWalletLastLoginDate:
          type: integer
          format: int64
          description: Last login date for digital wallet in Unix timestamp (milliseconds since epoch)
          example: 1734260400000
          maximum: 253402300799999
          minimum: 0
        digitalWalletLastLoginAuthMethod:
          type: string
          description: Authentication method used for last login to digital wallet
          example: Pin
          maxLength: 30
          minLength: 1
          pattern: ^[a-zA-Z0-9]{1,30}$
        additionalAttributes:
          $ref: '#/components/schemas/CustomerProfileAttributes'
      required:
      - email
      - firstName
      - lastName
      - memberNumber
      nullable: true
  responses:
    Unauthorized:
      description: 'The user could not be authenticated for this request.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-401:
              $ref: '#/components/examples/example-error-401'
    ServiceUnavailable:
      description: "temporary maintenance of service, try again later. The implication \nis that this is a temporary condition which will be alleviated \nafter some delay. If known, the length of the delay will be \nindicated in a Retry-After header. If no Retry-After is given, \nthe client SHOULD handle the response as it would for a 500 response. \nNote: The existence of the 503 status code does not imply that a \nserver will use it when becoming overloaded. Servers may simply \nrefuse the connection.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-503:
              $ref: '#/components/examples/example-error-503'
    NotFound:
      description: "Server has not found a resource with that URI. This may be \ntemporary and permanent condition. This status code is \ncommonly used when the server does not wish to reveal \nexactly why the request has been refused, or when no other \nresponse is applicable.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-404:
              $ref: '#/components/examples/example-error-404'
    Forbidden:
      description: 'The user is not permitted to access the requested operation and it cannot be completed.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-403:
              $ref: '#/components/examples/example-error-403'
    InternalServerError:
      description: "Server encountered an error processing request. This should not \nhappen normally, but it is a generic error message, given when \nno more specific message is suitable.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-500:
              $ref: '#/components/examples/example-error-500'
    UserIdentityContextResponse:
      description: User identify context response body. Payload fully encrypted.
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserIdentityContextResponse'
          examples:
            UserIdentityContextResponseData:
              $ref: '#/components/examples/user-identity-context-response'
    BadRequest:
      description: "The request could not be understood by the server due to malformed \nsyntax. The client SHOULD NOT repeat the request without \nmodifications.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-400-bad-request:
              $ref: '#/components/examples/example-error-400-bad-request'
  headers:
    Cache-Control:
      description: GIS mandatory response header. This is added by the Cognac sidecar.
      schema:
        type: string
        default: no-cache, no-store, must-revalidate
        deprecated: false
        example: no-cache, no-store, must-revalidate
        maxLength: 35
        minLength: 35
        pattern: ^no-cache, no-store, must-revalidate$
        nullable: false
  securitySchemes:
    ExternalTiaaUsCCAuth:
      type: oauth2
      description: OAuth2.0 Client Credentials Grant authentication using TIAA-US for external APIs
      flows:
        clientCredentials:
          tokenUrl: https://token.tiaa-dev.us.barclays.intranet:8443/as/token.oauth2
          scopes:
            read: read only
            write: write only