Skip to main content

methods/username-passkey/react-custom

For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.

The passkey hooks on ceremonies that the app provides, for example on a React Native passkey library. Exported at @convex-dev/auth/methods/username-passkey/react-custom.

Type Aliases​

PasskeyAuthenticationResponse​

type PasskeyAuthenticationResponse = object;

An authentication response in the WebAuthn JSON encoding, as the passkey libraries return it.

Properties​

PropertyType
idstring
rawIdstring
responseobject
response.authenticatorDatastring
response.clientDataJSONstring
response.signaturestring
response.userHandle?string | null
type"public-key"

PasskeyCeremonies​

type PasskeyCeremonies = object;

The passkey ceremonies of a platform, which an app implements to run the passkey hooks outside a browser. createUsernamePasskeyHooks takes one.

register and authenticate return the response of the platform as it is: the hooks keep only the fields the server accepts. For a failure they recognize, they return the matching PasskeyClientError. A thrown error named NotAllowedError or AbortError becomes CEREMONY_ABORTED, and any other thrown value becomes OTHER_ERROR.

Properties​

PropertyTypeDescription
authenticate(options) => Promise< | { response: PasskeyAuthenticationResponse; success: true; } | PasskeyClientFailure>-
autofill?objectPasskey autofill. Without it, autofill reports available: false.
autofill.authenticate(options, signal) => Promise< | { response: PasskeyAuthenticationResponse; success: true; } | PasskeyClientFailure>-
autofill.isAvailable() => Promise<boolean>-
autofill.onResume?(listener) => () => void-
isSupported() => booleanWhether this device can run passkey ceremonies.
register(options) => Promise< | { response: PasskeyRegistrationResponse; success: true; } | PasskeyClientFailure>-

PasskeyRegistrationResponse​

type PasskeyRegistrationResponse = object;

A registration response in the WebAuthn JSON encoding, as the passkey libraries return it.

Properties​

PropertyType
idstring
rawIdstring
responseobject
response.attestationObjectstring
response.clientDataJSONstring
response.transports?string[] | null
type"public-key"

Functions​

createUsernamePasskeyHooks()​

function createUsernamePasskeyHooks(ceremonies): object;

Make the passkey hooks on the given ceremonies. They take the same arguments and return the same results as the hooks of @convex-dev/auth/methods/username-passkey/react.

Call it once, at the top level of a module:

export const { useSignInWithUsernamePasskey, useAddPasskey, useRemovePasskey } =
  createUsernamePasskeyHooks(ceremonies);

Parameters​

ParameterType
ceremoniesPasskeyCeremonies

Returns​

object

useAddPasskey​
useAddPasskey: (api) => object;
Parameters​
ParameterType
apiAddPasskeyApi
Returns​
addPasskey​
addPasskey: () => Promise<AddPasskeyResult>;

Adds a passkey to the account of the signed-in user.

Returns an object with a success boolean flag. If it is false, the object has a userError field that tells why.

Returns​

Promise<AddPasskeyResult>

pending​
pending: boolean;

true while an addPasskey call is running.

useRemovePasskey​
useRemovePasskey: (api) => object;
Parameters​
ParameterType
apiRemovePasskeyApi
Returns​
pending​
pending: boolean;

true while a removePasskey call is running.

removePasskey​
removePasskey: (passkeyId) => Promise<RemovePasskeyResult>;

Removes the given passkey from the account of the signed-in user.

Returns an object with a success boolean flag. If it is false, the object has a userError field that tells why.

Parameters​
ParameterType
passkeyIdstring
Returns​

Promise<RemovePasskeyResult>

useSignInWithUsernamePasskey​
useSignInWithUsernamePasskey: (api) => object;
Parameters​
ParameterType
apiUsernamePasskeyApi
Returns​
autofill​
autofill: object;

The state of the autofill flow:

  • available: whether the platform can offer passkeys in the autocompletion list; null while the detection runs.
  • status: the state of the request; see PasskeyAutofillStatus.
  • lastError: the most recent failure, for display or logging.
autofill.available​
available: boolean | null;
autofill.lastError​
lastError:
  | {
  error: "PROTOCOL_ERROR";
}
  | {
  error: "UNKNOWN_CREDENTIAL";
}
  | {
  error: "CHALLENGE_EXPIRED";
}
  | {
  error: "CEREMONY_ABORTED";
}
  | {
  error: "PASSKEY_ALREADY_REGISTERED";
}
  | {
  error: "WEBAUTHN_UNSUPPORTED";
}
  | {
  cause: unknown;
  error: "OTHER_ERROR";
}
  | null;
autofill.status​
status: PasskeyAutofillStatus;
pending​
pending: boolean;

true while a sign-in runs: a signIn call, or an autofill sign-in that the server verifies (autofill.status is "signingIn"). A signIn call in this time returns ALREADY_PENDING.

signIn​
signIn: (__namedParameters) => Promise<SignInWithUsernamePasskeyResult>;

Runs the identifier-first passkey flow for the given username.

Returns an object with a status field.

If it is "complete" the sign-in (or the account creation) was successful and the client will establish an authenticated session with the Convex backend server. The flow field tells which one it was: "signUp" created a new account, "signIn" authenticated an existing one.

If it is "error" the returned object will have a userError field with additional details about why sign-in failed.

Parameters​
ParameterType
__namedParameters{ username: string; }
__namedParameters.usernamestring
Returns​

Promise<SignInWithUsernamePasskeyResult>

References​

AddPasskeyApi​

Re-exports AddPasskeyApi

AddPasskeyResult​

Re-exports AddPasskeyResult

AlreadyPendingFailure​

Re-exports AlreadyPendingFailure

PasskeyAutofillStatus​

Re-exports PasskeyAutofillStatus

PasskeyClientError​

Re-exports PasskeyClientError

PasskeyClientFailure​

Re-exports PasskeyClientFailure

RemovePasskeyApi​

Re-exports RemovePasskeyApi

RemovePasskeyResult​

Re-exports RemovePasskeyResult

RenamePasskeyResult​

Re-exports RenamePasskeyResult

SignInWithUsernamePasskeyResult​

Re-exports SignInWithUsernamePasskeyResult

UsernamePasskeyApi​

Re-exports UsernamePasskeyApi

UsernamePasskeyAutofillError​

Re-exports UsernamePasskeyAutofillError

WireCreationOptions​

Re-exports WireCreationOptions

WireRequestOptions​

Re-exports WireRequestOptions