Login #

How to login #

The login function initiates the login process with the AppKey server for a specific application. It follows the WebAuthN protocol, where the client requests a challenge from the AppKey server, which acts as the FIDO2 Relying Party. Since the Passkey is stored on the client, authentication occurs by signing the challenge using the private key securely stored in the client device’s keychain—accessible only through the user’s biometric authentication. The client then calls the loginComplete function, returning the signed challenge to the AppKey server, which verifies it against the user’s public key stored on the server.

The client can either pass in the handle or user name for login.

PassKey Recovery #

If a user loses their passkey due to a lost device or FIDO2 security key, they must contact the app developer to request a reset. This should be considered a last resort for account recovery. The decision to reset a passkey rests with the developer, not the Cosync Appkey system. The developer must ensure that the user is legitimate.

If the developer approves the reset, the user will receive a time-limited reset passkey token sent to the email associated with their handle. This token serves as the access credential for the addPasskey REST API, allowing the creation of a new passkey for the user.

The app will be notified of this requirement through the login REST API response. Specifically, the requireAddPasskey field in the response will be set to true (its default value is false).

URL #

    /api/appuser/login

Method #

    POST

Headers #

	app-token: "<App Token>"

Data Parameter #

    {
        handle: "<user handle>"
    }

Response: #

Success: #

StatusCode: #

    200 (OK)

Contents: #

    {
        rpId: "appkey.io",
        challenge: <FIDO2 challenge>,
        allowCredentials: [
            {
                id: <passkey id>,
                transports: [
                    "internal"
                ],
                type: "public-key"
            }
        ],
        timeout: 60000,
        userVerification: "preferred",
        user: {
            id: <user uuid>,
            name: <passkey name>,
            displayName: <user display name>,
            handle: <user handle>
        },
        requireAddPasskey: <bool>
    }

Error: #

StatusCode: #

    400 (BAD REQUEST)
    500 (INTERNAL SERVER ERROR)

Content: #

    {
        code: "<internal error code>",
        message: "<readable error description>"
    }

The internal codes are integers:

• 400 - invalid app token
• 401 - app no longer exists
• 402 - app is suspended
• 403 - missing parameter
• 404 - user account is suspended
• 413 - app is migrated
• 500 - internal server error
• 600 - invalid login credentials
• 603 - email does not exist
• 607 - user name does not exist