android {
defaultConfig {
minSdk = 21
}
}
This guide helps you upgrade your application to use yubikit-android 3.0. It highlights key changes that may affect your code, with migration steps and troubleshooting notes.
The minimum supported Android API level is now 21 (was 19). Update your app’s minSdkVersion as needed.
Update any usage of public API identifiers that previously used ALL CAPS abbreviations (e.g. getPinComplexityPolicyURL → getPinComplexityPolicyUrl).
Remove usage of deprecated APIs; they have been fully removed.
If you use FIDO/WebAuthn APIs:
Switch from BasicWebAuthnClient to WebAuthnClient, if you instantiate these clients directly.
Change your code to use ClientDataProvider for client data instead of passing raw byte arrays.
Update error handling: use AuthInvalidClientError to catch invalid PIN or UV errors.
If your code uses SDK generics like Result<T, E> in Kotlin, ensure you specify non-nullable type arguments (<T : Any>).
The minimum supported Android API level for yubikit-android is now 21 (Android 5.0, Lollipop).
This is an increase from the previous minimum, which was API level 19.
If your app’s minSdkVersion is set below 21, you must raise it to use yubikit-android 3.0.
android {
defaultConfig {
minSdk = 21
}
}
If your code references SDK identifiers using ALL CAPS abbreviations (such as PIN, RPID, URL, YK), update those references to their new CamelCase forms.
getPinComplexityPolicyURL → getPinComplexityPolicyUrl
YKInstrumentedTests → YkInstrumentedTests
See PR#230 for details.
The SDK now uses JSpecify (https://jspecify.dev/) nullness annotations, enforcing stricter rules about which types can be null.
If you use Kotlin, update any function or class generic parameters that interact with SDK types like Result<T, E>: generics must be non-nullable and use <T : Any>.
// Old
fun <T> returnsResult(): Result<T, Throwable> { ... }
// New
fun <T : Any> returnsResult(): Result<T, Throwable> { ... }
See PR#231.
If you use FIDO/WebAuthn APIs, you must now provide client data through a ClientDataProvider implementation (not as a raw byte array). Use the provided JsonClientData class.
// Old
byte[] clientData = ...
webAuthnClient.makeCredential(
/* byte[] */ clientData,
/* PublicKeyCredentialCreationOptions*/ options,
/* String */ effectiveDomain,
...
// New
import com.yubico.yubikit.fido.client.clientdata.JsonClientData;
byte[] clientData = ...
ClientDataProvider clientDataProvider = new JsonClientData(clientData);
webAuthnClient.makeCredential(
/* ClientDataProvider */ clientDataProvider,
/* PublicKeyCredentialCreationOptions*/ options,
/* String */ effectiveDomain,
...
See PR#233.
All APIs previously marked as deprecated have been removed. If your application depended on any deprecated items, update your code to supported alternatives.
See PR#237.
If you directly instantiate FIDO/WebAuthn clients:
Use WebAuthnClient in place of BasicWebAuthnClient.
// Old
Ctap2Session session = new Ctap2Session(connection);
BasicWebAuthnClient client = new BasicWebAuthnClient(session);
PublicKeyCredential credential = client.makeCredential(params);
String response = JSONObject(credential.toMap()).toString();
// New
List<Extension> extensions = ...; // provide list of extensions this client should process or null for default list containing defined WebAuthn extensions
WebAuthnClient client = WebAuthnClient.create(/* YubiKeyDevice */ device, extensions);
// Alternative way
// WebAuthnClient client = WebAuthnClient.create(/* YubiKeyConnection */ connection, extensions, scpKeyParams);
PublicKeyCredential credential = client.makeCredential(params);
String response = JSONObject(credential.toMap()).toString();
If you catch authentication errors in FIDO flows, use AuthInvalidClientError (instead of legacy errors like PinInvalidClientError).
Compile errors on missing APIs: Check if the item was deprecated and removed. Use the SDK documentation or release notes to find the correct replacement.
Generics issues in Kotlin: If you see type errors with Result<T, E>, update declarations to <T : Any>, ensuring that type arguments are non-nullable.
Client data handling: If previous code for FIDO/WebAuthn fails, ensure you pass a proper ClientDataProvider implementation.
For migration questions or issues, open a GitHub Issue.