Barclays User SSO Context API

openapi: 3.2.0
info:
  title: Authentication User SSO Context API
  description: Secure login for Barclays credit card customers to access online services
  version: '2.0'
tags:
- name: user-sso-context
  description: User sso context API
paths:
  /users/sso:
    summary: This api is used to facilitate single-sign-on customer into selected activity journey. This operation contains sensitive data in request and response payload.
    description: This api is used to facilitate single-sign-on customer into MOBILE/CWS for selected activity journey.
    post:
      tags:
      - user-sso-context
      summary: single-sign-on customer context.
      description: This api is used to facilitate single-sign-on customer into MOBILE/CWS for selected activity journey. Uses `auth_grant` token.
      operationId: request-sso
      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
      requestBody:
        description: SSO drop off request. Payload fully encrypted.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSSOContextRequest'
            examples:
              UserSSOContextRequest:
                $ref: '#/components/examples/user-sso-context-request'
      responses:
        '200':
          $ref: '#/components/responses/UserSSOContextResponse'
        '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.
    user-sso-context-response:
      value:
        data:
          expiry: 10
          resumeUrl: https://barclays-endpoint/to-be-opened-in-web-view/payload-response-fully-encrypted
    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.
    user-sso-context-request:
      value:
        data:
          identifier:
            id: 2c4717c4-e2f3-4071-2b86-b86890876322
            type: ACCOUNT_ID
          activityType: ADD_EXTERNAL_ACCOUNT
          channel: WEB
          product: SMG
          deviceIPAddress: 0.0.1.1
          additionalAttributes:
          - name: STATEMENT_REFERENCE
            value: Tmpjd1kyUmtZemt6WTJVeVl6a3haV1ZqTkRjME1UZGhMRGMxVXpCS00wazBUekU1UjFabE5FOVZVMEZNTms0NVJVdzBUVWMwTVVsQk5UUTBUa1ZGTUZRMFFVaEZSVUZLUTAxR1R6Y3k6YXR0ZXN0YXRpb24=
            type: text
    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.
    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
    UserSSOContextResponse:
      type: object
      additionalProperties: false
      deprecated: false
      description: User SSO Response.
      properties:
        data:
          $ref: '#/components/schemas/UserSSOContextResponseData'
      required:
      - data
      nullable: false
    Identifier:
      type: object
      additionalProperties: false
      description: An field for customer unique identifier.
      properties:
        id:
          type: string
          description: identifier id
          example: 2c4717c4-e2f3-4071-2b86-b86890876322
          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}$
          nullable: false
        type:
          type: string
          description: Type sent by customer for to identify allowed SSO activity
          enum:
          - CUSTOMER_ID
          - ACCOUNT_ID
          example: CUSTOMER_ID
      required:
      - id
      - type
      nullable: false
    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
    UserSSOContextResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: response payload for sso.
      properties:
        expiry:
          type: integer
          description: Resume URL expiry in seconds.
          example: 10
          maximum: 95
          minimum: 1
        resumeUrl:
          type: string
          description: Client/Partner endpoint where CWS/Mobile is expected to redirect after completing.
          example: https://idp.barclays.com
          maxLength: 300
          minLength: 1
          pattern: ^(?=.{1,300}$)https:\/\/[^\s/$.?#].[^\s]*$
          nullable: false
      nullable: false
    UserSSOContextRequest:
      type: object
      additionalProperties: false
      deprecated: false
      description: SSO Request Data
      properties:
        data:
          $ref: '#/components/schemas/UserSSOContextRequestData'
      required:
      - data
      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
    AdditionalSSOAttributes:
      type: array
      description: Additional attributes for SSO context
      items:
        $ref: '#/components/schemas/NameValueAttributePair'
      maxItems: 100
      minItems: 0
    UserSSOContextRequestData:
      type: object
      additionalProperties: false
      deprecated: false
      description: Request payload for User SSO context.
      properties:
        identifier:
          $ref: '#/components/schemas/Identifier'
        activityType:
          type: string
          description: Activity type sent by customer for CWS/MOB to identify allowed SSO activity
          enum:
          - ADD_EXTERNAL_ACCOUNT
          - MANAGE_EXTERNAL_ACCOUNT
          - VIEW_STATEMENT
          example: ADD_EXTERNAL_ACCOUNT
        product:
          type: string
          description: Client product/brand
          example: SMG
          maxLength: 20
          minLength: 3
          pattern: ^[A-Za-z0-9]{3,20}$
          nullable: false
        channel:
          type: string
          description: Channel field for the IDP page rendering.
          enum:
          - WEB
          - MOBILE
        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
        additionalAttributes:
          $ref: '#/components/schemas/AdditionalSSOAttributes'
      required:
      - activityType
      - channel
      - identifier
      - product
      nullable: false
  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'
    UserSSOContextResponse:
      description: SSO drop off response. Payload fully encrypted.
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserSSOContextResponse'
          examples:
            UserSSOContextResponse:
              $ref: '#/components/examples/user-sso-context-response'
    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'
    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