Credential Manager is a Jetpack API that supports multiple sign-in methods, such as username and password, passkeys, and federated sign-in solutions (such as Sign-in with Google) in a single API, thus simplifying the integration for developers.
Furthermore, for users, Credential Manager unifies the sign-in interface across authentication methods, making it clearer and easier for users to sign into apps, regardless of the method they choose.
This page explains the concept of passkeys and the steps to implementing client-side support for authentication solutions, including passkeys, using the Credential Manager API. There is also a separate FAQ page that provides answers to more detailed, specific questions.
Your feedback is a crucial part of improving the Credential Manager API. Share any issues you find or ideas for improving the API using the following link:
About passkeys
Passkeys are a safer and easier replacement for passwords. With passkeys, users can sign in to apps and websites using a biometric sensor (such as a fingerprint or facial recognition), PIN, or pattern. This provides a seamless sign-in experience, freeing your users from having to remember usernames or passwords.
Passkeys rely on WebAuthn (Web Authentication), a standard jointly developed by the FIDO Alliance and the World Wide Web Consortium (W3C). WebAuthn uses public-key cryptography to authenticate the user. The website or app that the user is signing into can see and store the public key, but never the private key. The private key is kept secret and safe. And because the key is unique and tied to the website or app, passkeys are un-phishable, adding further security.
Credential Manager allows users to create passkeys and store them in Google Password Manager.
Read User authentication with passkeys for guidance on how to implement seamless passkey authentication flows with Credential Manager.
Prerequisites
To use Credential Manager, complete the steps in this section.
Use a recent platform version
Credential Manager is supported on Android 4.4 (API level 19) and higher.
Add dependencies to your app
Add the following dependencies to your app module's build script:
Kotlin
dependencies { implementation("androidx.credentials:credentials:1.5.0-alpha05") // optional - needed for credentials support from play services, for devices running // Android 13 and below. implementation("androidx.credentials:credentials-play-services-auth:1.5.0-alpha05") }
Groovy
dependencies { implementation "androidx.credentials:credentials:1.5.0-alpha05" // optional - needed for credentials support from play services, for devices running // Android 13 and below. implementation "androidx.credentials:credentials-play-services-auth:1.5.0-alpha05" }
Preserve classes in ProGuard file
In your module's proguard-rules.pro
file, add the following directives:
-if class androidx.credentials.CredentialManager
-keep class androidx.credentials.playservices.** {
*;
}
Learn more about how to shrink, obfuscate, and optimize your app.
Add support for Digital Asset Links
To enable passkey support for your Android app, associate your app with a website that your app owns. You can declare this association by completing the following steps:
Create a Digital Asset Links JSON file. For example, to declare that the website
https://signin.example.com
and an Android app with the package namecom.example
can share sign-in credentials, create a file namedassetlinks.json
with the following content:[ { "relation" : [ "delegate_permission/common.handle_all_urls", "delegate_permission/common.get_login_creds" ], "target" : { "namespace" : "android_app", "package_name" : "com.example.android", "sha256_cert_fingerprints" : [ SHA_HEX_VALUE ] } } ]
The
relation
field is an array of one or more strings that describe the relationship being declared. To declare that apps and sites share sign-in credentials, specify the relationships asdelegate_permission/handle_all_urls
anddelegate_permission/common.get_login_creds
.The
target
field is an object that specifies the asset the declaration applies to. The following fields identify a website:namespace
web
site
The website's URL, in the format
https://domain[:optional_port]
; for example,https://www.example.com
.The domain must be fully-qualified., and optional_port must be omitted when using port 443 for HTTPS.
A
site
target can only be a root domain: you cannot limit an app association to a specific subdirectory. Don't include a path in the URL, such as a trailing slash.Subdomains are not considered to match: that is, if you specify the domain as
www.example.com
, the domainwww.counter.example.com
is not associated with your app.The following fields identify an Android app:
namespace
android_app
package_name
The package name declared in the app's manifest. For example, com.example.android
sha256_cert_fingerprints
The SHA256 fingerprints of your app's signing certificate. Host the Digital Assets Link JSON file at the following location on the sign-in domain:
https://domain[:optional_port]/.well-known/assetlinks.json
For example, if your sign-in domain is
signin.example.com
, host the JSON file athttps://signin.example.com/.well-known/assetlinks.json
.The MIME type for the Digital Assets Link file needs to be JSON. Make sure the server sends a
Content-Type: application/json
header in the response.Ensure that your host permits Google to retrieve your Digital Asset Link file. If you have a
robots.txt
file, it must allow the Googlebot agent to retrieve/.well-known/assetlinks.json
. Most sites can allow any automated agent to retrieve files in the/.well-known/
path so that other services can access the metadata in those files:User-agent: * Allow: /.well-known/
Add the following line to the manifest file under
<application>
:<meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
If you are using password sign-in through Credential Manager, follow this step to configure digital asset linking in manifest. This step is not required if you are only using passkeys.
Declare the association in the Android app. Add an object that specifies the
assetlinks.json
files to load. You must escape any apostrophes and quotation marks you use in the string. For example:<string name="asset_statements" translatable="false"> [{ \"include\": \"https://signin.example.com/.well-known/assetlinks.json\" }] </string>
> GET /.well-known/assetlinks.json HTTP/1.1 > User-Agent: curl/7.35.0 > Host: signin.example.com < HTTP/1.1 200 OK < Content-Type: application/json
Configure the Credential Manager
To configure and initialize a CredentialManager
object, add logic similar to
the following:
Kotlin
// Use your app or activity context to instantiate a client instance of // CredentialManager. val credentialManager = CredentialManager.create(context)
Java
// Use your app or activity context to instantiate a client instance of // CredentialManager. CredentialManager credentialManager = CredentialManager.create(context)
Indicate credential fields
On Android 14 and higher, the isCredential
attribute can be used to
indicate credential fields, such as username or password fields. This attribute
indicates that this view is a credential field that is intended to work with
Credential Manager and third party credential providers, while helping autofill
services provide better autofill suggestions. When the app uses the Credential
Manager API, the Credential Manager bottom sheet with available credentials is
displayed and there's no further need to show autofill's fill dialog for
username or password. In a similar way, there's no need to show autofill's
save dialog for passwords, as the app will request Credential Manager API
to save the credentials.
To use the isCredential
attribute, add it to the relevant Views:
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:isCredential="true"
...
/>
Sign in your user
To retrieve all the passkey and password options that are associated with the user's account, complete these steps:
Initialize the password and passkey authentication options:
Kotlin
// Retrieves the user's saved password for your app from their // password provider. val getPasswordOption = GetPasswordOption() // Get passkey from the user's public key credential provider. val getPublicKeyCredentialOption = GetPublicKeyCredentialOption( requestJson = requestJson )
Java
// Retrieves the user's saved password for your app from their // password provider. GetPasswordOption getPasswordOption = new GetPasswordOption(); // Get passkey from the user's public key credential provider. GetPublicKeyCredentialOption getPublicKeyCredentialOption = new GetPublicKeyCredentialOption(requestJson);
Use the options retrieved from the previous step to build the sign-in request.
Kotlin
val getCredRequest = GetCredentialRequest( listOf(getPasswordOption, getPublicKeyCredentialOption) )
Java
GetCredentialRequest getCredRequest = new GetCredentialRequest.Builder() .addCredentialOption(getPasswordOption) .addCredentialOption(getPublicKeyCredentialOption) .build();
Launch the sign-in flow:
Kotlin
coroutineScope.launch { try { val result = credentialManager.getCredential( // Use an activity-based context to avoid undefined system UI // launching behavior. context = activityContext, request = getCredRequest ) handleSignIn(result) } catch (e : GetCredentialException) { handleFailure(e) } } fun handleSignIn(result: GetCredentialResponse) { // Handle the successfully returned credential. val credential = result.credential when (credential) { is PublicKeyCredential -> { val responseJson = credential.authenticationResponseJson // Share responseJson i.e. a GetCredentialResponse on your server to // validate and authenticate } is PasswordCredential -> { val username = credential.id val password = credential.password // Use id and password to send to your server to validate // and authenticate } is CustomCredential -> { // If you are also using any external sign-in libraries, parse them // here with the utility functions provided. if (credential.type == ExampleCustomCredential.TYPE) { try { val ExampleCustomCredential = ExampleCustomCredential.createFrom(credential.data) // Extract the required credentials and complete the authentication as per // the federated sign in or any external sign in library flow } catch (e: ExampleCustomCredential.ExampleCustomCredentialParsingException) { // Unlikely to happen. If it does, you likely need to update the dependency // version of your external sign-in library. Log.e(TAG, "Failed to parse an ExampleCustomCredential", e) } } else { // Catch any unrecognized custom credential type here. Log.e(TAG, "Unexpected type of credential") } } else -> { // Catch any unrecognized credential type here. Log.e(TAG, "Unexpected type of credential") } } }
Java
credentialManager.getCredentialAsync( // Use activity based context to avoid undefined // system UI launching behavior activity, getCredRequest, cancellationSignal, <executor>, new CredentialManagerCallback<GetCredentialResponse, GetCredentialException>() { @Override public void onResult(GetCredentialResponse result) { handleSignIn(result); } @Override public void onError(GetCredentialException e) { handleFailure(e); } } ); public void handleSignIn(GetCredentialResponse result) { // Handle the successfully returned credential. Credential credential = result.getCredential(); if (credential instanceof PublicKeyCredential) { String responseJson = ((PublicKeyCredential) credential).getAuthenticationResponseJson(); // Share responseJson i.e. a GetCredentialResponse on your server to validate and authenticate } else if (credential instanceof PasswordCredential) { String username = ((PasswordCredential) credential).getId(); String password = ((PasswordCredential) credential).getPassword(); // Use id and password to send to your server to validate and authenticate } else if (credential instanceof CustomCredential) { if (ExampleCustomCredential.TYPE.equals(credential.getType())) { try { ExampleCustomCredential customCred = ExampleCustomCredential.createFrom(customCredential.getData()); // Extract the required credentials and complete the // authentication as per the federated sign in or any external // sign in library flow } catch (ExampleCustomCredential.ExampleCustomCredentialParsingException e) { // Unlikely to happen. If it does, you likely need to update the // dependency version of your external sign-in library. Log.e(TAG, "Failed to parse an ExampleCustomCredential", e); } } else { // Catch any unrecognized custom credential type here. Log.e(TAG, "Unexpected type of credential"); } } else { // Catch any unrecognized credential type here. Log.e(TAG, "Unexpected type of credential"); } }
The following example shows how to format the JSON request when you get a passkey:
{
"challenge": "T1xCsnxM2DNL2KdK5CLa6fMhD7OBqho6syzInk_n-Uo",
"allowCredentials": [],
"timeout": 1800000,
"userVerification": "required",
"rpId": "credential-manager-app-test.glitch.me"
}
The following example shows how a JSON response might look after you get a public key credential:
{
"id": "KEDetxZcUfinhVi6Za5nZQ",
"type": "public-key",
"rawId": "KEDetxZcUfinhVi6Za5nZQ",
"response": {
"clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiVDF4Q3NueE0yRE5MMktkSzVDTGE2Zk1oRDdPQnFobzZzeXpJbmtfbi1VbyIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
"authenticatorData": "j5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGQdAAAAAA",
"signature": "MEUCIQCO1Cm4SA2xiG5FdKDHCJorueiS04wCsqHhiRDbbgITYAIgMKMFirgC2SSFmxrh7z9PzUqr0bK1HZ6Zn8vZVhETnyQ",
"userHandle": "2HzoHm_hY0CjuEESY9tY6-3SdjmNHOoNqaPDcZGzsr0"
}
}
Handle exceptions when no credentials are available
In some cases, the user may not have any credentials available, or the user may
not grant consent to using an available credential. If getCredential()
is invoked and no credentials are not found, a NoCredentialException
is
returned. If this happens, your code should handle the NoCredentialException
instances.
Kotlin
try {
val credential = credentialManager.getCredential(credentialRequest)
} catch (e: NoCredentialException) {
Log.e("CredentialManager", "No credential available", e)
}
Java
try {
Credential credential = credentialManager.getCredential(credentialRequest);
} catch (NoCredentialException e) {
Log.e("CredentialManager", "No credential available", e);
}
On Android 14 or higher, you can reduce latency when showing the account
selector by using the prepareGetCredential()
method before calling
getCredential()
.
Kotlin
val response = credentialManager.prepareGetCredential(
GetCredentialRequest(
listOf(
<getPublicKeyCredentialOption>,
<getPasswordOption>
)
)
}
Java
GetCredentialResponse response = credentialManager.prepareGetCredential(
new GetCredentialRequest(
Arrays.asList(
new PublicKeyCredentialOption(),
new PasswordOption()
)
)
);
The prepareGetCredential()
method doesn't invoke UI elements. It only helps
you perform the preparation work so that you can later launch the remaining
get-credential operation (which involves UIs) through the getCredential()
API.
The cached data is returned in a PrepareGetCredentialResponse
object. If
there are existing credentials, the results will be cached and you can then
later launch the remaining getCredential()
API to bring up the account
selector with the cached data.
Registration flows
You can register a user for authentication using either a passkey or a password.
Create a passkey
To give users the choice to enroll a passkey and use it for reauthentication,
register a user credential using a CreatePublicKeyCredentialRequest
object.
Kotlin
fun createPasskey(requestJson: String, preferImmediatelyAvailableCredentials: Boolean) { val createPublicKeyCredentialRequest = CreatePublicKeyCredentialRequest( // Contains the request in JSON format. Uses the standard WebAuthn // web JSON spec. requestJson = requestJson, // Defines whether you prefer to use only immediately available // credentials, not hybrid credentials, to fulfill this request. // This value is false by default. preferImmediatelyAvailableCredentials = preferImmediatelyAvailableCredentials, ) // Execute CreateCredentialRequest asynchronously to register credentials // for a user account. Handle success and failure cases with the result and // exceptions, respectively. coroutineScope.launch { try { val result = credentialManager.createCredential( // Use an activity-based context to avoid undefined system // UI launching behavior context = activityContext, request = createPublicKeyCredentialRequest, ) handlePasskeyRegistrationResult(result) } catch (e : CreateCredentialException){ handleFailure(e) } } } fun handleFailure(e: CreateCredentialException) { when (e) { is CreatePublicKeyCredentialDomException -> { // Handle the passkey DOM errors thrown according to the // WebAuthn spec. handlePasskeyError(e.domError) } is CreateCredentialCancellationException -> { // The user intentionally canceled the operation and chose not // to register the credential. } is CreateCredentialInterruptedException -> { // Retry-able error. Consider retrying the call. } is CreateCredentialProviderConfigurationException -> { // Your app is missing the provider configuration dependency. // Most likely, you're missing the // "credentials-play-services-auth" module. } is CreateCredentialUnknownException -> ... is CreateCredentialCustomException -> { // You have encountered an error from a 3rd-party SDK. If you // make the API call with a request object that's a subclass of // CreateCustomCredentialRequest using a 3rd-party SDK, then you // should check for any custom exception type constants within // that SDK to match with e.type. Otherwise, drop or log the // exception. } else -> Log.w(TAG, "Unexpected exception type ${e::class.java.name}") } }
Java
public void createPasskey(String requestJson, boolean preferImmediatelyAvailableCredentials) { CreatePublicKeyCredentialRequest createPublicKeyCredentialRequest = // `requestJson` contains the request in JSON format. Uses the standard // WebAuthn web JSON spec. // `preferImmediatelyAvailableCredentials` defines whether you prefer // to only use immediately available credentials, not hybrid credentials, // to fulfill this request. This value is false by default. new CreatePublicKeyCredentialRequest( requestJson, preferImmediatelyAvailableCredentials); // Execute CreateCredentialRequest asynchronously to register credentials // for a user account. Handle success and failure cases with the result and // exceptions, respectively. credentialManager.createCredentialAsync( // Use an activity-based context to avoid undefined system // UI launching behavior requireActivity(), createPublicKeyCredentialRequest, cancellationSignal, executor, new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() { @Override public void onResult(CreateCredentialResponse result) { handleSuccessfulCreatePasskeyResult(result); } @Override public void onError(CreateCredentialException e) { if (e instanceof CreatePublicKeyCredentialDomException) { // Handle the passkey DOM errors thrown according to the // WebAuthn spec. handlePasskeyError(((CreatePublicKeyCredentialDomException)e).getDomError()); } else if (e instanceof CreateCredentialCancellationException) { // The user intentionally canceled the operation and chose not // to register the credential. } else if (e instanceof CreateCredentialInterruptedException) { // Retry-able error. Consider retrying the call. } else if (e instanceof CreateCredentialProviderConfigurationException) { // Your app is missing the provider configuration dependency. // Most likely, you're missing the // "credentials-play-services-auth" module. } else if (e instanceof CreateCredentialUnknownException) { } else if (e instanceof CreateCredentialCustomException) { // You have encountered an error from a 3rd-party SDK. If // you make the API call with a request object that's a // subclass of // CreateCustomCredentialRequest using a 3rd-party SDK, // then you should check for any custom exception type // constants within that SDK to match with e.type. // Otherwise, drop or log the exception. } else { Log.w(TAG, "Unexpected exception type " + e.getClass().getName()); } } } ); }
Format the JSON request
After you create a passkey, you must associate it with a user's account, and store the passkey's public key on your server. The following code example shows an how to format the JSON request when you create a passkey.
This blog post about bringing seamless authentication to your apps shows you how to format your JSON request when you create passkeys and when you authenticate using passkeys. It also explains why passwords aren't an effective authentication solution, how to leverage existing biometric credentials, how to associate your app with a website that you own, how to create passkeys, and how to authenticate using passkeys.
{
"challenge": "abc123",
"rp": {
"name": "Credential Manager example",
"id": "credential-manager-test.example.com"
},
"user": {
"id": "def456",
"name": "helloandroid@gmail.com",
"displayName": "helloandroid@gmail.com"
},
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
},
{
"type": "public-key",
"alg": -257
}
],
"timeout": 1800000,
"attestation": "none",
"excludeCredentials": [
{"id": "ghi789", "type": "public-key"},
{"id": "jkl012", "type": "public-key"}
],
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"residentKey": "required",
"userVerification": "required"
}
}
Set values for authenticatorAttachment
The authenticatorAttachment
parameter can only be set at credential creation
time. You can specify platform
, cross-platform
, or no value. In most cases,
no value is recommended.
platform
: To register the user's current device or prompt a password user to upgrade to passkeys after a sign-in, setauthenticatorAttachment
toplatform
.cross-platform
: This value is commonly used when enrolling multi-factor credentials and is not used in a passkey context.- No value: To provide users with the flexibility to create
passkeys on their preferred devices (such as in account settings), the
authenticatorAttachment
parameter shouldn't be specified when a user chooses to add a passkey. In most cases, leaving the parameter unspecified is the best option.
Prevent the creation of duplicate passkeys
List credential IDs in the optional excludeCredentials
array to prevent
the creation of a new passkey if one already exists with the same passkey
provider.
Handle the JSON response
The following code snippet shows an example JSON response for creating a public key credential. Learn more about how to handle the returned public key credential.
{
"id": "KEDetxZcUfinhVi6Za5nZQ",
"type": "public-key",
"rawId": "KEDetxZcUfinhVi6Za5nZQ",
"response": {
"clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoibmhrUVhmRTU5SmI5N1Z5eU5Ka3ZEaVh1Y01Fdmx0ZHV2Y3JEbUdyT0RIWSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViUj5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGRdAAAAAAAAAAAAAAAAAAAAAAAAAAAAEChA3rcWXFH4p4VYumWuZ2WlAQIDJiABIVgg4RqZaJyaC24Pf4tT-8ONIZ5_Elddf3dNotGOx81jj3siWCAWXS6Lz70hvC2g8hwoLllOwlsbYatNkO2uYFO-eJID6A"
}
}
Verify origin from client data JSON
The origin
represents the application or website that a
request comes from, and is used by passkeys to protect against phishing attacks.
Your app's server is required to check the client
data origin against an allowlist of approved apps and websites. If the server
receives a request from an app or website from an unrecognized origin, the
request should be rejected.
In the Web case, origin
reflects the same-site origin where
the credential was signed in. For example, given a URL of
https://www.example.com:8443/store?category=shoes#athletic
, the origin
is
https://www.example.com:8443
.
For Android apps, the user agent automatically sets origin
to the signature of
the calling app. This signature should be verified as a match on your server to
validate the caller of the passkey API. The Android origin
is a URI derived
from the SHA-256 hash of the APK signing certificate, such as:
android:apk-key-hash:<sha256_hash-of-apk-signing-cert>
The SHA-256 hashes of the signing certificates from a keystore can be found by running the following terminal command:
keytool -list -keystore <path-to-apk-signing-keystore>
The SHA-256 hashes are in a colon-delimited hexadecimal format
(91:F7:CB:F9:D6:81…
), and the Android origin
values are base64url-encoded.
This Python example demonstrates how to convert the hash format to a compatible,
colon-separated hexadecimal format:
import binascii
import base64
fingerprint = '91:F7:CB:F9:D6:81:53:1B:C7:A5:8F:B8:33:CC:A1:4D:AB:ED:E5:09:C5'
print("android:apk-key-hash:" + base64.urlsafe_b64encode(binascii.a2b_hex(fingerprint.replace(':', ''))).decode('utf8').replace('=', ''))
Replace the value of fingerprint
with your own value. Here is an example
result:
android:apk-key-hash:kffL-daBUxvHpY-4M8yhTavt5QnFEI2LsexohxrGPYU
You can then match that string as an allowed origin on your server. If you have multiple signing certificates, such as certificates for debugging and release, or multiple apps, then repeat the process and accept all those origins as valid on the server.
Save a user's password
If the user provides a username and password for an authentication flow in your
app, you can register a user credential that can be used to authenticate the
user. To do so, create a CreatePasswordRequest
object:
Kotlin
fun registerPassword(username: String, password: String) { // Initialize a CreatePasswordRequest object. val createPasswordRequest = CreatePasswordRequest(id = username, password = password) // Create credential and handle result. coroutineScope.launch { try { val result = credentialManager.createCredential( // Use an activity based context to avoid undefined // system UI launching behavior. activityContext, createPasswordRequest ) handleRegisterPasswordResult(result) } catch (e: CreateCredentialException) { handleFailure(e) } } }
Java
void registerPassword(String username, String password) { // Initialize a CreatePasswordRequest object. CreatePasswordRequest createPasswordRequest = new CreatePasswordRequest(username, password); // Register the username and password. credentialManager.createCredentialAsync( // Use an activity-based context to avoid undefined // system UI launching behavior requireActivity(), createPasswordRequest, cancellationSignal, executor, new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() { @Override public void onResult(CreateCredentialResponse result) { handleResult(result); } @Override public void onError(CreateCredentialException e) { handleFailure(e); } } ); }
Support credential recovery
If a user no longer has access to a device where they had stored their credentials, they might need to recover from a secure online backup. To learn more about how to support this credential recovery process, read the section titled "Recovering access or adding new devices" in this blog post: Security of Passkeys in the Google Password Manager.
Add support for password management tools with passkey endpoints well-known URLs
For seamless integration and future compatibility with password and credential management tools, we recommend adding support for passkey endpoints well-known URLs. This is an open protocol for aligned parties to formally advertise their support for passkeys and provide direct links for passkey enrollment and management.
- For a relying party at
https://example.com
, which has a website plus Android and iOS apps, the well-known URL would behttps://example.com/.well-known/passkey-endpoints
. When the URL is queried, the response should use the following schema
{ "enroll": "https://example.com/account/manage/passkeys/create" "manage": "https://example.com/account/manage/passkeys" }
To have this link open directly in your app instead of on the web, use Android app links.
Further details can be found in the passkey endpoints well-known URL explainer on GitHub.
Help users manage their passkeys by showing which provider created them
One challenge users face when managing multiple passkeys associated with a given app is identifying the correct passkey for editing or deletion. To assist with this problem, it's recommended that apps and websites include additional information like the provider that created the credential, the creation date and the last-used date in a passkeys list on your app's settings screen.The provider information is obtained by examining the AAGUID associated with the corresponding passkey. AAGUID can be found as part of a passkey's authenticator data.
For example, if a user creates a passkey on an Android-powered device using Google Password Manager, the RP then receives an AAGUID which looks something like this: "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4". The relying party can annotate the passkey in the passkey list to indicate that it was created using Google Password Manager.
To map an AAGUID to a passkey provider, RPs can use a community sourced repository of AAGUIDs. Look up the AAGUID on the list to find the passkey provider name and icon.
Read more about AAGUID integration.
Troubleshoot common errors
The following table shows several common error codes and descriptions, and provides some information about their causes:
Error code and description | Cause |
---|---|
On Begin Sign In Failure: 16: Caller has been temporarily blocked due to too many canceled sign-in prompts. | If you encounter this 24-hour cooldown period during development, you can reset it by clearing Google Play services' app storage. Alternatively, to toggle this cooldown on a test device or emulator, go
to the Dialer app and input the following code:
|
On Begin Sign In Failure: 8: Unknown internal error. |
|
CreatePublicKeyCredentialDomException: The incoming request cannot be validated | The app's package ID is not registered with your server. Validate this in your server-side integration. |
CreateCredentialUnknownException: During save password, found password failure response from one tap 16: Skipping password saving since the user is likely prompted with Android Autofill | This error occurs only on Android 13 and lower, and only if Google is the Autofill provider. In this case, users see a save prompt from Autofill and the password is saved to the Google Password Manager. Note that the credentials saved using Autofill with Google are bi-directionally shared with Credential Manager API. As a result, this error can be safely ignored. |
Additional resources
To learn more about the Credential Manager API and passkeys, view the following resources:
- Passkeys UX Guide
- Video: How to reduce reliance on passwords in Android apps with passkey support
- Codelab: Learn how to simplify auth journeys using Credential Manager API in your Android app
- Sample app: CredentialManager