Passkey Reference

Start Passkey Registration

Initiates the passkey registration process for a user. This generates WebAuthn registration options that should be passed to your WebAuthn library on the client side.

Arguments

userId string required

The ID of the user

emailOrUsername string required

The email address or username of the user

userDisplayName string

A human-readable display name for the user

passkeyDisplayName string

A custom display name for the passkey being created

additionalAllowedOrigin string

An additional origin to allow for passkey operations (beyond the default origin)

Successful Response

registrationOptions object

WebAuthn registration options to pass to your WebAuthn library

Error Types

CannotParseAdditionalAllowedOrigin

The additionalAllowedOrigin field was not formatted correctly as a valid origin

TooManyPasskeys

The user has reached the maximum number of passkeys allowed

UnexpectedError

An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.passkeys.startRegistration({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  emailOrUsername: "user@example.com",
  userDisplayName: "Example User",
  passkeyDisplayName: "My MacBook",
  additionalAllowedOrigin: "https://app.example.com",
});

if (result.ok) {
  console.log("Registration started successfully");
  // Pass registrationOptions to your WebAuthn library
  res.json({ registrationOptions: result.data.registrationOptions });
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.passkeys.start_registration(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    email_or_username="user@example.com",
    user_display_name="Example User",
    passkey_display_name="My MacBook",
    additional_allowed_origin="https://app.example.com"
)

if is_ok(result):
    print("Registration started successfully")
    # Pass registration_options to your WebAuthn library
    return JSONResponse({"registrationOptions": result.data.registration_options})
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

StartPasskeyRegistrationCommand command = StartPasskeyRegistrationCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .emailOrUsername("user@example.com")
    .userDisplayName("Example User")
    .passkeyDisplayName("My MacBook")
    .additionalAllowedOrigin("https://app.example.com")
    .build();

try {
    StartPasskeyRegistrationResponse response = client.passkeys.startRegistration(command);
    System.out.println("Registration started successfully");
    // Pass registrationOptions to your WebAuthn library
} catch (StartPasskeyRegistrationException.TooManyPasskeys e) {
    System.out.println("Too many passkeys: " + e.getDetails());
} catch (StartPasskeyRegistrationException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new StartPasskeyRegistrationCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    EmailOrUsername = "user@example.com",
    UserDisplayName = "Example User",
    PasskeyDisplayName = "My MacBook",
    AdditionalAllowedOrigin = "https://app.example.com"
};

try
{
    var response = await client.Passkeys.StartRegistrationAsync(command);
    Console.WriteLine("Registration started successfully");
    // Pass RegistrationOptions to your WebAuthn library
}
catch (StartPasskeyRegistrationException.TooManyPasskeys ex)
{
    Console.WriteLine("Too many passkeys");
}
catch (StartPasskeyRegistrationException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    registrationOptions: {
      /* pass this to your webauthn library */
    }
  }
}

StartPasskeyRegistrationResponse(
    registration_options={
        # pass this to your webauthn library
    }
)

StartPasskeyRegistrationResponse(
    registrationOptions={
        /* pass this to your webauthn library */
    }
)

StartPasskeyRegistrationResponse
{
    RegistrationOptions = {
        /* pass this to your webauthn library */
    }
}

Finish Passkey Registration

Completes the passkey registration process. This should be called after the user has completed the WebAuthn registration ceremony on the client side.

Arguments

userId string required

The ID of the user

publicKey JsonValue required

The public key credential returned from the WebAuthn registration

additionalAllowedOrigin string

An additional origin to allow for passkey operations (beyond the default origin)

Successful Response

Returns an empty response on success

Error Types

CannotParseAdditionalAllowedOrigin

The additionalAllowedOrigin field was not formatted correctly as a valid origin

NoRegistrationChallengeFound

No registration challenge was found for this user

OriginNotAllowed

The origin of the request does not match the expected origin from the registration challenge

PasskeyForUserAlreadyExists

A passkey with this credential ID already exists for the user

UnexpectedError

An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.passkeys.finishRegistration({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  publicKey: publicKeyCredential, // from WebAuthn API
  additionalAllowedOrigin: "https://app.example.com",
});

if (result.ok) {
  console.log("Passkey registration completed successfully");
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.passkeys.finish_registration(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    public_key=public_key_credential,  # from WebAuthn API
    additional_allowed_origin="https://app.example.com"
)

if is_ok(result):
    print("Passkey registration completed successfully")
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FinishPasskeyRegistrationCommand command = FinishPasskeyRegistrationCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .publicKey(publicKeyCredential) // from WebAuthn API
    .additionalAllowedOrigin("https://app.example.com")
    .build();

try {
    FinishPasskeyRegistrationResponse response = client.passkeys.finishRegistration(command);
    System.out.println("Passkey registration completed successfully");
} catch (FinishPasskeyRegistrationException.PasskeyForUserAlreadyExists e) {
    System.out.println("Passkey already exists for user");
} catch (FinishPasskeyRegistrationException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new FinishPasskeyRegistrationCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    PublicKey = publicKeyCredential, // from WebAuthn API (JsonElement)
    AdditionalAllowedOrigin = "https://app.example.com"
};

try
{
    var response = await client.Passkeys.FinishRegistrationAsync(command);
    Console.WriteLine("Passkey registration completed successfully");
}
catch (FinishPasskeyRegistrationException.PasskeyForUserAlreadyExists ex)
{
    Console.WriteLine("Passkey already exists for user");
}
catch (FinishPasskeyRegistrationException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {}
}

FinishPasskeyRegistrationResponse()

FinishPasskeyRegistrationResponse()

FinishPasskeyRegistrationResponse()

Start Passkey Authentication

Initiates the passkey authentication process for a user. This generates WebAuthn authentication options that should be passed to your WebAuthn library on the client side.

Arguments

userId string required

The ID of the user

additionalAllowedOrigin string

An additional origin to allow for passkey operations (beyond the default origin)

Successful Response

authenticationOptions object

WebAuthn authentication options to pass to your WebAuthn library

Error Types

CannotParseAdditionalAllowedOrigin

The additionalAllowedOrigin field was not formatted correctly as a valid origin

NoPasskeysRegisteredForUser

The user has no passkeys registered

UnexpectedError

An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.passkeys.startAuthentication({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  additionalAllowedOrigin: "https://app.example.com",
});

if (result.ok) {
  console.log("Authentication started successfully");
  // Pass authenticationOptions to your WebAuthn library
  res.json({ authenticationOptions: result.data.authenticationOptions });
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.passkeys.start_authentication(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    additional_allowed_origin="https://app.example.com"
)

if is_ok(result):
    print("Authentication started successfully")
    # Pass authentication_options to your WebAuthn library
    return JSONResponse({"authenticationOptions": result.data.authentication_options})
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

StartPasskeyAuthenticationCommand command = StartPasskeyAuthenticationCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .additionalAllowedOrigin("https://app.example.com")
    .build();

try {
    StartPasskeyAuthenticationResponse response = client.passkeys.startAuthentication(command);
    System.out.println("Authentication started successfully");
    // Pass authenticationOptions to your WebAuthn library
} catch (StartPasskeyAuthenticationException.NoPasskeysRegisteredForUser e) {
    System.out.println("No passkeys registered for user");
} catch (StartPasskeyAuthenticationException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new StartPasskeyAuthenticationCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    AdditionalAllowedOrigin = "https://app.example.com"
};

try
{
    var response = await client.Passkeys.StartAuthenticationAsync(command);
    Console.WriteLine("Authentication started successfully");
    // Pass AuthenticationOptions to your WebAuthn library
}
catch (StartPasskeyAuthenticationException.NoPasskeysRegisteredForUser ex)
{
    Console.WriteLine("No passkeys registered for user");
}
catch (StartPasskeyAuthenticationException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    authenticationOptions: {
      /* pass this to your webauthn library */
    }
  }
}

StartPasskeyAuthenticationResponse(
    authentication_options={
        # pass this to your webauthn library
    }
)

StartPasskeyAuthenticationResponse(
    authenticationOptions={/* pass this to your webauthn library */}
)

StartPasskeyAuthenticationResponse
{
    AuthenticationOptions = {
        /* pass this to your webauthn library */
    }
}

Finish Passkey Authentication

Completes the passkey authentication process. This should be called after the user has completed the WebAuthn authentication ceremony on the client side.

Arguments

userId string required

The ID of the user

publicKey JsonValue required

The public key credential returned from the WebAuthn authentication

additionalAllowedOrigin string

An additional origin to allow for passkey operations (beyond the default origin)

Successful Response

Returns an empty response on success

Error Types

CannotParseAdditionalAllowedOrigin

The additionalAllowedOrigin field was not formatted correctly as a valid origin

NoAuthenticationChallengeFound

No authentication challenge was found for this user

OriginNotAllowed

The origin of the request does not match the expected origin from the authentication challenge

UnexpectedError

An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.passkeys.finishAuthentication({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  publicKey: publicKeyCredential, // from WebAuthn API
  additionalAllowedOrigin: "https://app.example.com",
});

if (result.ok) {
  console.log("Passkey authentication completed successfully");
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.passkeys.finish_authentication(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    public_key=public_key_credential,  # from WebAuthn API
    additional_allowed_origin="https://app.example.com"
)

if is_ok(result):
    print("Passkey authentication completed successfully")
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FinishPasskeyAuthenticationCommand command = FinishPasskeyAuthenticationCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .publicKey(publicKeyCredential)  // from WebAuthn API
    .additionalAllowedOrigin("https://app.example.com")
    .build();

try {
    FinishPasskeyAuthenticationResponse response = client.passkeys.finishAuthentication(command);
    System.out.println("Passkey authentication completed successfully");
} catch (FinishPasskeyAuthenticationException.OriginNotAllowed e) {
    System.out.println("Origin not allowed: " + e.getDetails());
} catch (FinishPasskeyAuthenticationException.NoAuthenticationChallengeFound e) {
    System.out.println("No authentication challenge found");
} catch (FinishPasskeyAuthenticationException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new FinishPasskeyAuthenticationCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    PublicKey = publicKeyCredential,  // from WebAuthn API
    AdditionalAllowedOrigin = "https://app.example.com"
};

try
{
    var response = await client.Passkeys.FinishAuthenticationAsync(command);
    Console.WriteLine("Passkey authentication completed successfully");
}
catch (FinishPasskeyAuthenticationException.OriginNotAllowed ex)
{
    Console.WriteLine($"Origin not allowed: {ex.Details}");
}
catch (FinishPasskeyAuthenticationException.NoAuthenticationChallengeFound ex)
{
    Console.WriteLine("No authentication challenge found");
}
catch (FinishPasskeyAuthenticationException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {}
}

FinishPasskeyAuthenticationResponse()

FinishPasskeyAuthenticationResponse()

FinishPasskeyAuthenticationResponse()

Fetch All Passkeys For User

Retrieves all registered passkeys for a specific user.

Arguments

userId string required

The ID of the user

Successful Response

passkeys array

Array of passkey information objects

Error Types

UnexpectedError

An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.passkeys.fetchAllPasskeysForUser({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
});

if (result.ok) {
  console.log("User passkeys fetched successfully");
  console.log(`Found ${result.data.passkeys.length} passkeys`);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.passkeys.fetch_all_passkeys_for_user(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)

if is_ok(result):
    print("User passkeys fetched successfully")
    print(f"Found {len(result.data.passkeys)} passkeys")
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FetchAllPasskeysForUserCommand command = FetchAllPasskeysForUserCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .build();

try {
    FetchAllPasskeysForUserResponse response = client.passkeys.fetchAllPasskeysForUser(command);
    System.out.println("User passkeys fetched successfully");
    System.out.println("Found " + response.getPasskeys().size() + " passkeys");
} catch (FetchAllPasskeysForUserException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new FetchAllPasskeysForUserCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
};

try
{
    var response = await client.Passkeys.FetchAllPasskeysForUserAsync(command);
    Console.WriteLine("User passkeys fetched successfully");
    Console.WriteLine($"Found {response.Passkeys.Count} passkeys");
}
catch (FetchAllPasskeysForUserException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    passkeys: [
      {
        displayName: null,
        credentialId: "Qig5uty-0-H..."
      },
      {
        displayName: "My MacBook",
        credentialId: "Pbahw-a-h..."
      }
    ]
  }
}

FetchAllPasskeysForUserResponse(
    passkeys=[
        PasskeyInfo(
            display_name=None,
            credential_id="Qig5uty-0-H..."
        ),
        PasskeyInfo(
            display_name="My MacBook",
            credential_id="Pbahw-a-h..."
        )
    ]
)

FetchAllPasskeysForUserResponse(
    passkeys=[
        PasskeyInfo(
            displayName=null,
            credentialId="Qig5uty-0-H..."
        ),
        PasskeyInfo(
            displayName="My MacBook",
            credentialId="Pbahw-a-h..."
        )
    ]
)

FetchAllPasskeysForUserResponse
{
    Passkeys = [
        new PasskeyInfo
        {
            DisplayName = null,
            CredentialId = "Qig5uty-0-H..."
        },
        new PasskeyInfo
        {
            DisplayName = "My MacBook",
            CredentialId = "Pbahw-a-h..."
        }
    ]
}

Deregister Passkey

Removes a specific passkey for a user.

Arguments

userId string required

The ID of the user

credentialId string required

The credential ID of the passkey to remove

Successful Response

Returns an empty response on success

Error Types

PasskeyNotFound

The specified passkey does not exist for this user

UnexpectedError

An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.passkeys.deregisterPasskey({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  credentialId: "Qig5uty-0-H...",
});

if (result.ok) {
  console.log("Passkey deregistered successfully");
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.passkeys.deregister_passkey(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    credential_id="Qig5uty-0-H..."
)

if is_ok(result):
    print("Passkey deregistered successfully")
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

DeregisterPasskeyCommand command = DeregisterPasskeyCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .credentialId("Qig5uty-0-H...")
    .build();

try {
    DeregisterPasskeyResponse response = client.passkeys.deregisterPasskey(command);
    System.out.println("Passkey deregistered successfully");
} catch (DeregisterPasskeyException.PasskeyNotFound e) {
    System.out.println("Passkey not found");
} catch (DeregisterPasskeyException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new DeregisterPasskeyCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    CredentialId = "Qig5uty-0-H..."
};

try
{
    await client.Passkeys.DeregisterPasskeyAsync(command);
    Console.WriteLine("Passkey deregistered successfully");
}
catch (DeregisterPasskeyException.PasskeyNotFound)
{
    Console.WriteLine("Passkey not found");
}
catch (DeregisterPasskeyException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {}
}

DeregisterPasskeyResponse()

DeregisterPasskeyResponse()

DeregisterPasskeyResponse()

Deregister All Passkeys For User

Removes all passkeys for a user.

Arguments

userId string required

The ID of the user

Successful Response

Returns an empty response on success

Error Types

UnexpectedError

An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.passkeys.deregisterAllPasskeysForUser({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
});

if (result.ok) {
  console.log("All passkeys deregistered successfully");
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.passkeys.deregister_all_passkeys_for_user(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)

if is_ok(result):
    print("All passkeys deregistered successfully")
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

DeregisterAllPasskeysForUserCommand command = DeregisterAllPasskeysForUserCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .build();

try {
    client.passkeys.deregisterAllPasskeysForUser(command);
    System.out.println("All passkeys deregistered successfully");
} catch (DeregisterAllPasskeysForUserException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new DeregisterAllPasskeysForUserCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
};

try
{
    await client.Passkeys.DeregisterAllPasskeysForUserAsync(command);
    Console.WriteLine("All passkeys deregistered successfully");
}
catch (DeregisterAllPasskeysForUserException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {}
}

DeregisterAllPasskeysForUserResponse()

DeregisterAllPasskeysForUserResponse()

DeregisterAllPasskeysForUserResponse
{
}

Configuring Passkey Settings

You can configure passkey settings in the 'passkeys_config.jsonc' file.

Arguments

hostname string required

Hostname for the WebAuthn relying party (without protocol). Examples: "example.com", "localhost:3000", "app.example.com". This should match the domain where your application is hosted.

max_passkeys_per_user number

Maximum number of passkeys allowed per user. Defaults to 5, maximum is 10.

{
    // Hostname for the WebAuthn relying party (without protocol)
    // Examples: "example.com", "localhost:3000", "app.example.com"
    "hostname": "example.com",

    // Maximum number of passkeys allowed per user (default: 5, max: 10)
    "max_passkeys_per_user": 5
}