Authentication Methods

Get Help
1

I’m trying to create a authentication method for a user via User Managent.

Request here is successful.

Request to Auth0

{
"aaguid" : "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4",
"credential_backed_up" : true,
"credential_device_type" : "multi_device",
"identity_user_id" : "5e85abee76cbbf0be8eeb5ad",
"key_id" : "ykDzwnbRTA5NljkRGr1pyA==",
"name" : "Mike Tester",
"public_key" : "pQECAyYgASFYIMToxELNxpyiN3mIFDOeLkTkrwCVASaicveWCBpH1tmKIlggm9Xztf8+ulRa3xiccNeHwMQ6kfjO7HxgvXE4j4Z+NNM=",
"relying_party_identifier" : "``example.com``",
"transports" : [ "internal", "hybrid" ],
"type" : "passkey",
"user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",
"user_handle" : "3xK7mQ2vN9pL4sT8wY6cR1aF5dH0jUeZ"
}

Response from Auth0.
{
"aaguid" : "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4",
"created_at" : "2026-08-22T13:35:49.471Z",
"credential_backed_up" : true,
"credential_device_type" : "multi_device",
"id" : "passkey|dev_uq4tzUImRW3Zb53g",
"identity_user_id" : "5e85abee76cbbf0be8eeb5ad",
"key_id" : "ykDzwnbRTA5NljkRGr1pyA==",
"public_key" : "pQECAyYgASFYIMToxELNxpyiN3mIFDOeLkTkrwCVASaicveWCBpH1tmKIlggm9Xztf8+ulRa3xiccNeHwMQ6kfjO7HxgvXE4j4Z+NNM=",
"relying_party_identifier" : "``example.com``",
"transports" : [ "internal", "hybrid" ],
"type" : "passkey",
"user_agent" : "Chrome 151.0.0 / Windows 10.0.0",
"user_handle" : "P_UfCc1NsZEmlXvNcC6KEzyG1WrUt-qtziw0a3Br5-NRtMCtbpfOkBTBBalhHSA_hCbZUHBVGKM4vCg7DBPZ_w"
}

It looks like Auth0 ignores user_handle?

user_handle
string
Applies to passkeys only. The user handle of the user identity.

2

"user_handle" : "P_UfCc1NsZEmlXvNcC6KEzyG1WrUt-qtziw0a3Br5-NRtMCtbpfOkBTBBalhHSA_hCbZUHBVGKM4vCg7DBPZ_w"

Here API seems to returns always the same user handle despite of the passed value. For example send user_handle=“A” or user_handle=“B” → End result here is the same in both cases "P_UfCc1NsZEmlXvNcC6KEzyG1WrUt-qtziw0a3Br5-NRtMCtbpfOkBTBBalhHSA_hCbZUHBVGKM4vCg7DBPZ_w"

3

Any comments about this?

5

Hi @DuxXXXX

Welcome to the Auth0 Community!

I understand that you are looking for information as to why the user_handle value specified in the request to Auth0 is being ignored in the response, and the returned value is always the same.

The user_handle field in the authentication method creation request is not a user-configurable identifier — it is a system-generated unique handle that Auth0 creates and manages internally for each authentication method.

Root Cause

The user_handle parameter in the request payload is not intended to be set by the client. Auth0 generates this value automatically when an authentication method is created, ensuring each method has a unique, immutable identifier within the system. Any value you pass in the request is ignored by design, and Auth0 always returns its own generated handle in the response.

Recommended Solution

If you are creating authentication methods via the User Management API, follow these steps:

  1. Construct your POST request to the /api/v2/users/{id}/authentication-methods endpoint with the required fields for the authentication method type (for example, type, name, and method-specific details like credential for passkeys).

  2. Omit the user_handle field from your request payload entirely. Do not attempt to set it — Auth0 will generate it automatically.

  3. Extract the user_handle from the response after the authentication method is successfully created. This is the authoritative handle for that method going forward.

  4. Store the returned user_handle if you need to reference this authentication method later (for example, when updating or deleting it).

The user_handle serves as Auth0’s internal reference for the authentication method and is not meant to be a custom identifier. If you need to associate custom metadata with an authentication method, use the user_metadata field on the user object instead, or store your own mapping in your application database.

Hope this helped clear the details!

Have a great one,
Gerald

7

Let’s imagine that a user wants to create a passkey.

a) The system first needs to create PublicKeyCredentialCreationOptions. This option data is created in our system / master system.

As far as I understand, the user.id field in these options should refer to the master system’s user ID, rather than to a user ID from an external system such as Auth0.

At this point, the Auth0 user_handle is not even known because the authentication method has not yet been created. Is my understanding correct?

b) The user then creates a credential (passkey) based on the previously generated PublicKeyCredentialCreationOptions.

The credential data is sent to our backend (the master system). Once the passkey data has been successfully inserted into our database, we create the corresponding authentication method via the Auth0 Management API.

Our requirement is that, regardless of what happens with Auth0 or any other external identity provider, we must always be able to recreate or provision all passkeys in another provider’s system if necessary—for example, in an emergency or migration scenario.

I am not a WebAuthn expert, but this seems rather problematic if we cannot use the user_handle that is already used by our master database. I also just don’t understand why the Auth0 documentation presents user_handle as part of the POST authentication-method request:
Auth0 — POST /api/v2/users/{id}/authentication-methods

I have to say that the Auth0 documentation has been, at least in my experience, quite ambiguous.
For example, in the documentation above, some fields do not specify how their values should be encoded. The public_key field explicitly states that it uses Base64, whereas WebAuthn data is commonly represented using Base64URL encoding. For several other fields, developers essentially have to guess which encoding is expected.

There are also cases where the documentation appears to be outdated by several years. For example, it tells developers to navigate to a particular section in the Auth0 Dashboard and select a specific option, but when you actually navigate there, the UI has changed and the referenced option or data no longer exists.

Overall, I would appreciate clarification on which identifier should be used as the WebAuthn user.id / Auth0 user_handle, and how these identifiers are expected to relate to each other. This is particularly important for our architecture because Auth0 should be treated as an external provider, while the master system needs to remain the source of truth for the passkey data.

8

@gerald.czifra I would appreciate your comments on the matter. Wondering why is issue has been set as resolved?