Hanko Mobile Integration Guide (Beta):About Hanko: Hanko is a privacy-first authentication and user management provider that offers customizable, open-source authentication solutions focused on the passkey era. It provides both hosted cloud services and self-hosted options, supporting flexible login methods including passkeys, passwords, OAuth providers, and email passcodes.What This Guide Covers: This guide demonstrates how to integrate Hanko authentication into native mobile applications using direct API calls. Since Hanko doesn’t yet provide native mobile SDKs, you’ll learn to implement the authentication flow using HTTP requests to Hanko’s REST API.Key Technologies: Native mobile development (iOS/Android), HTTP requests, Hanko REST API, JWT tokens, Passkeys (iOS 16+, Android 9+)Prerequisites: Mobile development knowledge (iOS/Android), Hanko Cloud account (free at cloud.hanko.io), understanding of HTTP/REST APIsIntegration Tasks You’ll Complete:
Currently, Hanko doesn’t provide native mobile SDKs like the web components. This guide shows how to integrate Hanko authentication into your native mobile app using direct API calls.
- Check if users exist using the user management API
- Create new users via the user creation endpoint
- Send and verify passcodes for email verification
- Handle JWT session tokens for authentication
- Optionally implement passkey registration for faster login
- Implement proper error handling for various API responses
- Authenticate users in your mobile app backend
This guide focuses on the passwordless flow, so passwords will be ignored.
Passkeys are only supported on iOS 16+ and Android 9+.
1
Check if the user exists
After an email input was shown and the user provided their email, you should check if the user already exists.
You can do that by using the Get user details by email endpoint.You will either get an HTTP status code of
200 or 404. If you get 200, remember the id returned in the response object and go to step ‘Send a passcode’.
If you get 404, go to the next step.2
Create user
When the user does not already exist, you will need to create the user before you can verify the email. The user can be created using the Create a user endpoint.You will either get an HTTP status code of
200 or 409. If you get 409, then the user already exists, and you can obtain the users id from the success response of the endpoint mentioned in the previous step.
If you get 200, remember the id returned in the response object.3
Send a passcode
To verify an email address or to log in the user, you need to send a passcode to the provided email address and verify that the user has access to it. To send a passcode just use the Initialize passcode login endpoint.
You need to provide the user’s
id you obtained in one of the previous steps. If sending the passcode was successful, you will get an id for the passcode in the response object. Remember this id, because you will need it to finalize the passcode flow.When the user entered the passcode, send it together with the passcode id from the Init endpoint to the Finalize passcode login endpoint.
When the passcode is correct you will get a JWT either as a cookie or in the X-Auth-Token header (depends on the configuration of the Hanko backend) .The user is now logged in. To verify (in your backend) that the JWT is valid, see our Backend guide.Optionally you can offer the user to register a passkey now, enabling a faster login flow the next time. See the next step on how to do it.4
Create a passkey (optional)
To create a passkey you will need to use the native APIs that Google
and Apple
provide for their platforms. Find out how to use them here
(Apple) and here (Android).For both you will need
PublicKeyCredentialAttestationOptions which you can get from the Initialize WebAuthn registration endpoint.After the native system APIs were called with the options you will receive a PublicKeyCredentialAttestationResponse. Send the response to the Finalize WebAuthn registration endpoint.
If successful, the user can use the created passkey to login faster the next time.The two endpoints (Initialize WebAuthn registration and Finalize WebAuthn registration) mentioned above can only be called with a valid JWT.
In order for Android to work with the Hanko backend you will need to add an “APK Key Hash” to either Change
webauthn.relying_party.origins or in the advanced page in the settings at Hanko Cloud.
Use this command to create the “APK Key Hash”:-alias and -keystore flag values to your personal values.5
Login with a passkey (optional)
In order to use a passkey for login, add a button (“Sign in with a passkey”) under your email input. After interaction with the button, call the native APIs that Google
and Apple.
Find out how to use them here
(Apple) and here (Android).For both you will need
PublicKeyCredentialAssertionOptions which you can get from the Initialize WebAuthn login endpoint.After the native system APIs were called with the options you will receive a PublicKeyCredentialAssertionResponse. Send the response to the Finalize WebAuthn login endpoint.
If successful you will get back a JWT either as a cookie or in the X-Auth-Token header (depends on the configuration of the Hanko backend).The user is now logged in. To verify (in your backend) that the JWT is valid, see our Backend guide.