REST API Usage

The Device Token feature is part of the authentication REST API and additionally provides a protected call to associate new device tokens with a user account.

Initial Authentication

  • Use any authentication flow to authenticate the REST client (see .../rest/public/authentication/ in the Loginapp REST API specification)
  • The authentication must result in roles required to access the "device token registration" URLs in the protected part of the Loginapp REST API.

Device Token Registration

  • See .../rest/protected/my/tokens/device-tokens in the Loginapp REST API specification
  • The REST client needs to be authenticated and has enough roles to access the resources.
  • Provides calls to:
    • List valid device tokens registered for the logged-in user (also used to find out whether device tokens can be registered or not)
    • Add ("register") a new device token, i.e. an EC public key with some additional optional information
    • Delete a device token: may be called by the REST client if e.g. an account is removed from a mobile app or alike.

Device Token Authentication

  • See .../rest/public/authentication/device-token
  • Provides calls to:
    • Get a challenge given a device token ID
    • Check a JWT with the signed challenge
  • The device token authentication step can be used as 1st or 2nd step. 
  • Device token authentication as first step: It usually makes sense to configure two different target applications, i.e. one application for the case if no device token has been registered yet and one if the user chooses to authenticate with the device token:
    • Target application without device token step
      • Username + password as the first step
      • Any second step (e.g. MTAN)
    • Target application with device token step as the first authentication factor
      • Device token step
      • Any second factor (e.g. MTAN)
  • Device token authentication as the second step: It usually makes sense in conjunction with another 2nd factor in the flow:
    • Username + password as first step
    • Selection of: device tokens and alternative factors (e.g. MTAN) as 2nd step
    • see also REST API  examples below
    • Like this, the REST client can use the alternative 2nd factor (e.g. MTAN) if no device token has been registered yet.
    • This allows the REST client to register a new device token and use the device token from this point on.