TSB Bank Authorization Server APIs API

openapi: 3.2.0
info:
  title: OTK Server Authorization Server APIs API
  version: 4.3.1
  description: All API's available in OAuth Toolkit server
servers:
- url: https://apis.tsb.co.uk:443/
  variables:
    request.url.host:
      default: unknown
    request.url.port:
      default: unknown
tags:
- name: Authorization Server APIs
paths:
  /auth/oauth/v2/authorize:
    get:
      tags:
      - Authorization Server APIs
      description: Initializes an OAuth 2.0 flow using a response_type. See RFC 6749 (https://tools.ietf.org/html/rfc6749) for more details.
      operationId: Get_request_authorization
      parameters:
      - name: mag-identifier
        in: header
        required: false
        x-is-map: false
        description: The mag-identifier is used in conjunction with response_type 'code'.  This field is required for Mobile clients. It must represent a valid registered mobile device. A client is identified as a mobile client if its registered SCOPE includes 'msso'.
        schema:
          type: string
      - name: client_id
        in: query
        required: true
        x-is-map: false
        description: This is the 'client_id' of the requesting client. Maximum 255 characters.
        schema:
          type: string
      - name: response_type
        in: query
        required: true
        x-is-map: false
        description: 'MUST be one of the listed available values. Any response_type other than ''code'' or ''token'' is only supported in conjunction with scope=openid. As per the OAuth specification: ''code'' is used for authorization code grant type flow, ''token'' is used for implicit grant type flow, ''token id_token'' is an extension provided by OpenID Connect, and ''code id_token'', ''id_token'', and ''none'' are extensions provided by OpenID Connect Multiple Response Types'
        schema:
          type: string
          enum:
          - code
          - token
          - token id_token
          - code id_token
          - id_token
          - code token
          - code id_token token
          - none
      - name: response_mode
        in: query
        required: false
        x-is-map: false
        description: 'Specify the method of returning the authorization response. As per the OpenID specification, use of this parameter is NOT RECOMMENDED if you are using the same response mode as the default response mode for the given response type. It MUST be one of the listed values in order to be accepted: ''query'', ''fragment'', ''form_post''.'
        schema:
          type: string
          enum:
          - query
          - fragment
          - form_post
      - name: redirect_uri
        in: query
        required: false
        x-is-map: false
        description: The 'redirect_uri' that was registered for this client. It is required if multiple redirect_uri's have been registered for this client. If the scope contains openid, this field becomes MANDATORY.
        schema:
          type: string
      - name: scope
        in: query
        required: false
        x-is-map: false
        description: Only SCOPE values that were registered for this client will be granted. If only non-matching SCOPE values are requested, the request will fail.
        schema:
          type: string
      - name: nonce
        in: query
        required: false
        x-is-map: false
        description: This is required for response_type 'token id_token'.  Typically, in an OpenID authorization scheme, the nonce represents a cryptographically strong random  string that is used to prevent intercepted responses from being reused.
        schema:
          type: string
      - name: display
        in: query
        required: false
        x-is-map: false
        description: This is optional and used within the context of OpenID Connect (ie, response_type 'token id_token'). This parameter is not used here but forwarded to the /authorize/login API. Currently only 'page', 'social_login' (MAG only) and 'local' (MAG only) are supported by default. The value 'social_login' will create a JSON message response instead of an HTML page containing a list of social login providers. The value 'local' will prevent the authorization server from displaying the social login buttons. This is the case if a user selected the local enterprise button for logging in.
        schema:
          type: string
          enum:
          - ''
          - page
          - social_login
          - local
          default: ''
      - name: prompt
        in: query
        required: false
        x-is-map: false
        description: This is used within the context of OpenID Connect. Indicates whether the server should prompt for login/consent. It is a space separated list of different values. The server supports the values 'none', 'login' and 'consent'. 'none' is only respected if 'id_token_hint' is not empty. 'consent' is only respected if the current user has an active OAuth session using the same client and the same SCOPE.
        schema:
          type: string
          default: login consent
      - name: id_token_hint
        in: query
        required: false
        x-is-map: false
        description: This is used within the context of OpenID Connect. Contains a previously issued id_token. This parameter is only respected for 'prompt=none' or 'prompt=none consent'.
        schema:
          type: string
      - name: acr_values
        in: query
        required: false
        x-is-map: false
        description: This is used within the context of OpenID Connect. Indicates which acr (additional cryptography) classes are acceptable for the user authentication. It is a space separated list of different values.
        schema:
          type: string
      - name: code_challenge
        in: query
        required: false
        x-is-map: false
        description: The code_challenge value in the context of PKCE (RFC 7636).
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: false
        x-is-map: false
        description: The method that was used to create the code_challenge (plain or S256).
        schema:
          type: string
      - name: state
        in: query
        required: false
        x-is-map: false
        description: Value opaque to the server, used by the client to track its session. It will be returned as received.
        schema:
          type: string
      - name: login_hint
        in: query
        required: false
        x-is-map: false
        description: A suggested username. This parameter is described in the OpenID Connect core specification.
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers:
            location:
              description: 'Location (URL) includes these required parameters: action=(display or login depending on ''prompt'' and ''id_token_hint'') & sessionID & sessionData (a JWT containing a JSON message holding session data)'
              schema:
                type: string
        '302':
          $ref: '#/components/responses/auth302'
        '400':
          description: Invalid parameters | Invalid redirect_uri | invalid client type | invalid response type | invalid code_challenge/method
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3000103 (missing or invalid parameters), 3000112 (code_challenge or code_challenge_method invalid), 3000114 (invalid redirect uri), 3000116 (invalid response type), 3000130 (invalid client type)'
              schema:
                type: string
                default: '3000130'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '401':
          description: The client could not be authenticated.
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3000201 (client could not be authenticated), 3000306 (The given JWT for client authentication is invalid), 3000307 (Request is a replay attack), 3000308(Replay attack protection could not be applied)'
              schema:
                type: string
                default: '3000201'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '403':
          description: Forbidden.
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3000203 (SSL required)'
              schema:
                type: string
                default: '3000203'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '405':
          description: The HTTP method is not valid
          headers:
            Allow:
              description: This header is required by RFC 2616 and contains a comma separated list of valid HTTP methods.
              schema:
                type: string
                default: GET,POST
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '500':
          description: unknown error
          headers:
            x-ca-err:
              description: Custom error extension
              schema:
                type: string
                default: '3000000'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
  /auth/oauth/health:
    get:
      tags:
      - Authorization Server APIs
      description: An endpoint that can be used to verify your OAuth authentication flow is working correctly. Is only usable if the context variable otk.health.apikey is defined inside the corresponding service policy.
      operationId: Get_request_health_check
      parameters:
      - name: apikey
        in: query
        required: true
        description: Key that needs to be used to perform health check.
        schema:
          type: string
          default: Empty
      responses:
        '200':
          description: Responds with "SUCCESS"
        '500':
          description: Responds with "error". This can be due to missing or incorrect API key. Check audit log messages for more information.
        '503':
          description: Responds with "error". Returned on health check failure. This can be returned due to bad database configuration, bad certification configuration, etc. Check the audit log messages for more information.
  /auth/oauth/v2/authorize/login:
    get:
      tags:
      - Authorization Server APIs
      description: Receives a request as the result of a redirect from the /auth/oauth/v2/authorize endpoint. Creates a login page or forwards a request to the consent screen.
      operationId: Get_request_authorize_login
      parameters:
      - name: action
        in: query
        required: true
        x-is-map: false
        description: ''
        schema:
          type: string
          default: display
      - name: sessionID
        in: query
        required: true
        x-is-map: false
        description: The current session which was initiated at the initial authorization request.
        schema:
          type: string
      - name: sessionData
        in: query
        required: true
        x-is-map: false
        description: A signed JSON Web Token (JWT) which contains a JSON structure holding values initially received and validated at authorize.
        schema:
          type: string
      responses:
        '200':
          description: Responds with authentication form
        '400':
          description: invalid parameters | The session has expired or already been granted
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3001103 (missing or duplicate parameters), 3001110 (session expired)'
              schema:
                type: string
                default: '3001103'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '403':
          description: Forbidden.
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3001203 (SSL required)'
              schema:
                type: string
                default: '3001203'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '405':
          description: The HTTP method is not valid
          headers:
            Allow:
              description: This header is required by RFC 2616 and contains a comma separated list of valid HTTP methods.
              schema:
                type: string
                default: POST
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '500':
          description: Unknown error.
          headers:
            x-ca-err:
              description: Custom error extension
              schema:
                type: string
                default: '3001000'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
    post:
      tags:
      - Authorization Server APIs
      description: Authenticates a user during the OAuth 2.0 response_type flow OR Authenticates a user during the OAuth 2.0 response_type using a social platform.
      operationId: Post_request_authorize_login
      parameters:
      - name: action
        in: query
        required: true
        x-is-map: false
        description: Display the login screen, Authenticate the user (login), Cancel the login process or Reset
        schema:
          type: string
          enum:
          - reset
          - display
          - login
          - cancel
          default: login
      - name: username
        in: query
        required: false
        x-is-map: false
        description: The username of the user to authenticate.
        schema:
          type: string
      - name: password
        in: query
        required: false
        x-is-map: false
        description: The password for user authentication.
        schema:
          type: string
          format: password
      - name: sessionID
        in: query
        required: true
        x-is-map: false
        description: The current session which was initiated at the initial authorization request.
        schema:
          type: string
      - name: sessionData
        in: query
        required: true
        x-is-map: false
        description: A signed JSON Web Token (JWT) which contains a JSON structure holding values initially received and validated at authorize.
        schema:
          type: string
      - name: code
        in: query
        required: false
        x-is-map: false
        description: An OAuth 2.0 authorization_code issued by a social login provider.
        schema:
          type: string
      - name: provider
        in: query
        required: false
        x-is-map: false
        description: The social login provider that issued the 'code'. This value is specified as part of the redirect_uri configured with each social login provider.
        schema:
          type: string
      - name: response_mode
        in: query
        required: false
        x-is-map: false
        description: 'Specify the method of returning the authorization response. As per the OpenID specification, use of this parameter is NOT RECOMMENDED if you are using the same response mode as the default response mode for the given response type. It MUST be one of the listed values in order to be accepted: ''query'', ''fragment'', ''form_post''.'
        schema:
          type: string
          enum:
          - query
          - fragment
          - form_post
      - name: oauth_token
        in: query
        required: false
        x-is-map: false
        description: OAuth 1.0 token when the social login provider is used with OAuth 1.0.
        schema:
          type: string
      - name: oauth_verifier
        in: query
        required: false
        x-is-map: false
        description: OAuth 1.0 verifier when the social login provider is used with OAuth 1.0.
        schema:
          type: string
      responses:
        '200':
          description: Authenticates a user during the OAuth 2.0 response_type flow OR if authentication was successful the API auto-form posts to the API that handles the consent screen, /authorize/consent (login via social provider)
          headers:
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '302':
          description: Authentication Denied, If the redirect_uri is not available, the server displays an HTML page showing the error and error_description. The HTTP status will be '400'
          headers:
            location:
              description: Location (URL) has the 'error', 'error_description' and 'state' (if provided) parameters attached.
              schema:
                type: string
            x-ca-err:
              description: 'Custom error extension. Possible values: 3001103 (missing or duplicate parameters), 3001116 (invalid response type)'
              schema:
                type: string
                default: '3001103'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '400':
          description: 'Invalid parameters | The session has expired or already been granted | invalid response type '
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3001103 (missing or duplicate parameters), 3001116 (invalid response type)'
              schema:
                type: string
                default: '3001103'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '401':
          description: The resource owner could not be authenticated. An HTML page displaying an authentication error will be returned.
          headers:
            x-ca-err:
              description: Custom error extension
              schema:
                type: string
                default: '3001202'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '403':
          description: Forbidden.
          headers:
            x-ca-err:
              description: Custom error extension
              schema:
                type: string
                default: '3001203'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '405':
          description: The HTTP method is not valid
          headers:
            Allow:
              description: This header is required by RFC 2616 and contains a comma separated list of valid HTTP methods.
              schema:
                type: string
                default: POST
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '500':
          description: Unknown error.
          headers:
            x-ca-err:
              description: Custom error extension
              schema:
                type: string
                default: '3001000'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
  /auth/oauth/v2/authorize/consent:
    post:
      tags:
      - Authorization Server APIs
      description: 'Handles the ''deny'' and ''grant'' result of a resource owner''s decision at the consent page when ''action'' is: ''consent'', the API returns an HTML page for the user to grant or deny the request. ''grant'', the API handles the ''grant'' result of the owner''s decision at the consent page. ''deny'', the API handles the ''deny'' result of the owner''s decision at the consent page.'
      operationId: Post_request_authorize_consent
      parameters:
      - name: response_mode
        in: query
        required: false
        x-is-map: false
        description: 'Specify the method of returning the authorization response. As per the OpenID specification, use of this parameter is NOT RECOMMENDED if you are using the same response mode as the default response mode for the given response type. It MUST be one of the listed values in order to be accepted: ''query'', ''fragment'', ''form_post''.'
        schema:
          type: string
          enum:
          - query
          - fragment
          - form_post
      responses:
        '200':
          description: Success, redirect to client redirect url
          headers:
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '302':
          description: Access was denied, redirect to client redirect with error
          headers:
            location:
              description: "If 'action' is 'grant': the redirect location will include the query parameters: state(if provided) and code.  In the 'implicit' response flow, the query parameters include: redirect_uri, access_token, expires_in, token_type, scope, id_token, id_token_type and state.  \nIf 'action' is 'deny':  the redirect will location include the 'x-ca-err', 'error', 'error_description' and 'state' (if provided) parameters.  In such a case the 'error' is 'access_denied'"
              schema:
                type: string
            x-ca-err:
              description: 'Custom error extension. Possible values: 3002116 (invalid response type)'
              schema:
                type: string
                default: '3002116'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '400':
          description: Invalid parameters
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3002103 (missing or duplicate parameters), 3002110 (session expired), 3002116 (invalid response type), 3002135 (token limit reached)'
              schema:
                type: string
                default: '3002103'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '401':
          description: The resource owner could not be authenticated. An HTML page displaying an authentication error will be returned.
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3002202 (resource owner could not be authenticated)'
              schema:
                type: string
                default: '3002202'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '403':
          description: Forbidden.
          headers:
            x-ca-err:
              description: 'Custom error extension. Possible values: 3002203 (SSL required)'
              schema:
                type: string
                default: '3002203'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '405':
          description: The HTTP method is not valid
          headers:
            Allow:
              description: This header is required by RFC 2616 and contains a comma separated list of valid HTTP methods.
              schema:
                type: string
                default: POST
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '500':
          description: Unknown error.
          headers:
            x-ca-err:
              description: Custom error extension
              schema:
                type: string
                default: '3002203'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                action:
                  description: Deny or Grant the resource with scope requested.
                  type: string
                  enum:
                  - deny
                  - grant
                  default: grant
                sessionID:
                  type: string
                sessionData:
                  description: A signed JSON Web Token (JWT) which contains a JSON structure holding values initially received and validated at authorize.
                  type: string
              required:
              - action
              - sessionID
              - sessionData
  /connect/session/logout:
    post:
      tags:
      - Authorization Server APIs
      description: The resource owner deletes his active session on the OAuth server.
      operationId: Create_resource_owner_logout_
      parameters:
      - name: mag-identifier
        in: header
        required: false
        description: '[MAG]: mobile clients MUST use this header. It must represent a valid registered device.'
        schema:
          type: string
      - name: logout_apps
        in: query
        required: false
        description: '[MAG]: mobile clients MAY use this parameter to invalidate all related oauth token.'
        schema:
          type: string
          default: 'true'
      - name: authorization
        in: header
        required: true
        description: 'The HTTP basic authorization header containing the client credentials as base64 encoded string (authorization: Basic base64(client_id:client_secret)).'
        schema:
          type: string
      - name: id_token
        in: query
        required: true
        description: 'The id_token that represents the authenticated user.

          [MAG]: Mobile clients may omit this parameter; mag-identifier will be used instead.'
        schema:
          type: string
      - name: id_token_type
        in: query
        required: false
        description: The id_token_type to be invalidated. Currently ignored.
        schema:
          type: string
          default: urn:ietf:params:oauth:grant-type:jwt-bearer
      responses:
        '200':
          description: Resource owner successfully logged out
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_status:
                    type: string
                    example: logged out
        '204':
          description: No Content, applicable to OPTIONS request with preflight configuration
          headers:
            Access-Control-Allow-Methods:
              description: Allowable Methods, POST
              schema:
                type: string
                default: POST
        '400':
          description: Bad Request
          headers:
            x-ca-err:
              description: 'Custom error extension.  Possible values:  3006103 (missing or duplicate parameters), 3006107 (mag-identifier invalid), 3006134 (request did not match CORS requirements) '
              schema:
                type: string
                default: '3006103'
            Pragma:
              description: Pragma browser directive
              schema:
                type: string
                default: no-cache
            Cache-Control:
              description: Cache-Control browser directive
              schema:
                type: string
                default: no-store
        '401':
          description: The client could not be authenticated.
    

# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tsb-bank/refs/heads/main/openapi/tsb-bank-authorization-server-apis-api-openapi.yml