Skip to main content

GetAuthInfo

GET 
/portfolios/:portfolioId/authinfo

Get the AuthInfo for the given portfolio.

If the portfolio does not have an online session, this will return a 400 status code.

If it does, the response describes whether session TAN is available or active and which auth methods are available for the given portfolio (this information depends on the broker and the user's account settings).

The response determines which of the following operations can be used and which are required to successfully perform an operation in a portfolio:

The list of available AuthMethods should only be presented to the user if session TAN is not active (yet). The list and names are defined by our partner brokers. All auth methods are generally categorized using the flow attribute:

flowrequires challenge?Description
TANnothe simplest flow: no challenge is required to perform the operation. the TAN is simply sent as parameter tan
CHALLENGE_RESPONSEyesa challenge must be created using the createXYZChallenge operations and the challenge must be presented to the user. The user can then execute the action using the challengeId and challengeResponse parameters. If the auth method has challengeResponseIsOnlyConfirmation=true, that challengeResponse is always an empty string and users do not enter a TAN. Otherwise, a text field labelled with tanFieldLabel must be displayed where the user enteirs their challengeResponse.
DECOUPLEDnothe operation is executed without any TAN, but returns a decoupledOperationId which can be used to read the action's status. Users will authorize the action in another frontend (usually in their broker's app). Note that currently DECOUPLED auth methods only work for enabling session TAN.
  • If sessionTanActive is true: Session TAN has been enabled for the session that currently backs the portfolio. In this case, all operations like CreateTrade can be executed right away without an authMethod. The UI should not show a dropdown with the auth methods in this case.
  • If sessionTanActive is false but sessionTanSupported is true: the user can enable session TAN using CreateSessionTanChallenge / EnableSessionTan.
  • If allOperationsRequireSessionTan is true, the auth methods can ONLY be used for enabling session TAN.
  • Otherwise, the authMethods can be used to perform individual operations.
sessionTanActivesessionTanSupportedallOperationsRequireSessionTanDescription
truetrue-Session TAN has been enabled for the session that currently backs the portfolio. In this case, all operations like CreateTrade, ChangeOrder, CancelOrder can be executed right away without an authMethod. The UI should not show a dropdown with the auth methods in this case.
falsetruetruethe user can enable session TAN using the provided auth methods via CreateSessionTanChallenge / EnableSessionTan. All other operations can only take place after session TAN has been enabled.
falsetruefalsethe user can enable any operation (enable session tan, create trade, cancel order, change order) using the provided auth methods

Note that it is possible that brokers only reveal all details about the available auth methods TOGETHER with the first GetChallenge request. This special behavior can be simulated with our demo broker when the flag lazyAuthMethods=true is specified upon creation of a demo account. In those accounts, the GetAuthInfo endpoint will initially return a single "placeholder" method with {flow: "CHALLENGE_RESPONSE", isDefaultMethod: true, ...}.

In the situation where there is exactly one auth method like this, frontends may immediately request the challenge for the desired operation without waiting for the user to click the get challenge button (for Session TAN, this means that as soon as the user opens the dialog for enabling session TAN, CreateSessionTanChallenge can be called). In the case described here, AuthInfo will be populated with the actual list of auth methods when the create challenge request returns (also, the corresponding WebSocket event is published to notify about this change). GetAuthInfo must be called again in this case and repopulate the corresponding frontend (e.g. the name of the auth method will become available etc.). So what is done in this case is: request a challenge for the unknown default method in order to get both a challenge and an update of the auth methods.

Note that usually challenges have effects like an SMS or some broker app notification for the end user, so it is important to keep the requested challenge info, even when auth info is refreshed. For example, if there is a select box with the auth method list, that box must keep its selected id while updating the now-available label. This way, the user can use the first requested challenge, as the frontend will still be in the right state.

Request​

Responses​

Ok