0
# WebAuthn Authentication Operations
1

2
Core WebAuthn registration and authentication functionality. These methods handle the complete ceremony flow including credential creation, user verification, and response formatting.
3

4
## Capabilities
5

6
### Registration Flow
7

8
Initiates WebAuthn credential registration (attestation) ceremony.
9

10
```typescript { .api }
11
/**
12
 * Begin authenticator registration via WebAuthn attestation
13
 * @param options - Registration configuration including server options
14
 * @returns Promise resolving to registration response for server verification
15
 */
16
function startRegistration(options: StartRegistrationOpts): Promise<RegistrationResponseJSON>;
17

18
interface StartRegistrationOpts {
19
  /** Output from @simplewebauthn/server's generateRegistrationOptions() */
20
  optionsJSON: PublicKeyCredentialCreationOptionsJSON;
21
  /** Try to silently create a passkey with the password manager that the user just signed in with. Defaults to false */
22
  useAutoRegister?: boolean;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { startRegistration } from '@simplewebauthn/browser';
30

31
// Basic registration
32
const registrationResponse = await startRegistration({
33
  optionsJSON: {
34
    rp: { name: 'My App', id: 'example.com' },
35
    user: {
36
      id: 'dGVzdC11c2VyLWlk', // base64url encoded user ID
37
      name: 'user@example.com',
38
      displayName: 'John Doe'
39
    },
40
    challenge: 'Y2hhbGxlbmdl', // base64url encoded challenge
41
    pubKeyCredParams: [{ alg: -7, type: 'public-key' }],
42
    timeout: 60000,
43
    attestation: 'none'
44
  }
45
});
46

47
// Auto-register after authentication
48
const autoRegResponse = await startRegistration({
49
  optionsJSON: serverOptions,
50
  useAutoRegister: true
51
});
52

53
// Send response to server for verification
54
const verificationResult = await fetch('/verify-registration', {
55
  method: 'POST',
56
  headers: { 'Content-Type': 'application/json' },
57
  body: JSON.stringify(registrationResponse)
58
});
59
```
60

61
### Authentication Flow
62

63
Initiates WebAuthn credential authentication (assertion) ceremony.
64

65
```typescript { .api }
66
/**
67
 * Begin authenticator login via WebAuthn assertion
68
 * @param options - Authentication configuration including server options
69
 * @returns Promise resolving to authentication response for server verification
70
 */
71
function startAuthentication(options: StartAuthenticationOpts): Promise<AuthenticationResponseJSON>;
72

73
interface StartAuthenticationOpts {
74
  /** Output from @simplewebauthn/server's generateAuthenticationOptions() */
75
  optionsJSON: PublicKeyCredentialRequestOptionsJSON;
76
  /** Initialize conditional UI to enable logging in via browser autofill prompts. Defaults to false */
77
  useBrowserAutofill?: boolean;
78
  /** Ensure a suitable <input> element is present when useBrowserAutofill is true. Defaults to true */
79
  verifyBrowserAutofillInput?: boolean;
80
}
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
import { startAuthentication, browserSupportsWebAuthnAutofill } from '@simplewebauthn/browser';
87

88
// Basic authentication
89
const authResponse = await startAuthentication({
90
  optionsJSON: {
91
    challenge: 'Y2hhbGxlbmdl', // base64url encoded challenge
92
    rpId: 'example.com',
93
    timeout: 60000,
94
    userVerification: 'preferred'
95
  }
96
});
97

98
// Authentication with autofill (conditional UI)
99
if (await browserSupportsWebAuthnAutofill()) {
100
  const autofillResponse = await startAuthentication({
101
    optionsJSON: serverOptions,
102
    useBrowserAutofill: true
103
  });
104
}
105

106
// Disable input validation (advanced usage)
107
const skipValidationResponse = await startAuthentication({
108
  optionsJSON: serverOptions,
109
  useBrowserAutofill: true,
110
  verifyBrowserAutofillInput: false
111
});
112

113
// Send response to server for verification
114
const verificationResult = await fetch('/verify-authentication', {
115
  method: 'POST',
116
  headers: { 'Content-Type': 'application/json' },
117
  body: JSON.stringify(authResponse)
118
});
119
```
120

121
## Response Types
122

123
The authentication methods return structured JSON responses ready for server verification.
124

125
### Registration Response
126

127
```typescript { .api }
128
interface RegistrationResponseJSON {
129
  /** Credential ID as base64url string */
130
  id: Base64URLString;
131
  /** Raw credential ID as base64url string */
132
  rawId: Base64URLString;
133
  /** Attestation response data */
134
  response: AuthenticatorAttestationResponseJSON;
135
  /** How the authenticator is attached to the device */
136
  authenticatorAttachment?: AuthenticatorAttachment;
137
  /** Results of client extensions processing */
138
  clientExtensionResults: AuthenticationExtensionsClientOutputs;
139
  /** Always 'public-key' */
140
  type: PublicKeyCredentialType;
141
}
142

143
interface AuthenticatorAttestationResponseJSON {
144
  /** Client data as base64url string */
145
  clientDataJSON: Base64URLString;
146
  /** Attestation object as base64url string */
147
  attestationObject: Base64URLString;
148
  /** Authenticator data as base64url string (L3 optional) */
149
  authenticatorData?: Base64URLString;
150
  /** Available transport methods */
151
  transports?: AuthenticatorTransportFuture[];
152
  /** Public key algorithm identifier (L3 optional) */
153
  publicKeyAlgorithm?: COSEAlgorithmIdentifier;
154
  /** Public key as base64url string (L3 optional) */
155
  publicKey?: Base64URLString;
156
}
157
```
158

159
### Authentication Response
160

161
```typescript { .api }
162
interface AuthenticationResponseJSON {
163
  /** Credential ID as base64url string */
164
  id: Base64URLString;
165
  /** Raw credential ID as base64url string */
166
  rawId: Base64URLString;
167
  /** Assertion response data */
168
  response: AuthenticatorAssertionResponseJSON;
169
  /** How the authenticator is attached to the device */
170
  authenticatorAttachment?: AuthenticatorAttachment;
171
  /** Results of client extensions processing */
172
  clientExtensionResults: AuthenticationExtensionsClientOutputs;
173
  /** Always 'public-key' */
174
  type: PublicKeyCredentialType;
175
}
176

177
interface AuthenticatorAssertionResponseJSON {
178
  /** Client data as base64url string */
179
  clientDataJSON: Base64URLString;
180
  /** Authenticator data as base64url string */
181
  authenticatorData: Base64URLString;
182
  /** Authentication signature as base64url string */
183
  signature: Base64URLString;
184
  /** User handle as base64url string (optional) */
185
  userHandle?: Base64URLString;
186
}
187
```
188

189
## Supporting Types
190

191
Transport and attachment types used in responses:
192

193
```typescript { .api }
194
type AuthenticatorTransportFuture =
195
  | 'ble'
196
  | 'cable'
197
  | 'hybrid'
198
  | 'internal'
199
  | 'nfc'
200
  | 'smart-card'
201
  | 'usb';
202

203
type AuthenticatorAttachment = 'platform' | 'cross-platform';
204

205
type PublicKeyCredentialType = 'public-key';
206

207
type COSEAlgorithmIdentifier = number;
208
```
209

210
## Error Handling
211

212
Both authentication methods can throw `WebAuthnError` with specific error codes, or standard `Error` for basic validation failures:
213

214
```typescript
215
import { startRegistration, WebAuthnError } from '@simplewebauthn/browser';
216

217
try {
218
  const response = await startRegistration({ optionsJSON });
219
} catch (error) {
220
  if (error instanceof WebAuthnError) {
221
    // Handle specific WebAuthn errors
222
    console.log('WebAuthn error:', error.code, error.message);
223
  } else {
224
    // Handle general errors (e.g., "WebAuthn is not supported in this browser")
225
    console.log('General error:', error.message);
226
  }
227
}
228
```
229

230
## Browser Autofill Requirements
231

232
When using `useBrowserAutofill: true`, ensure your HTML contains an input element with WebAuthn in its autocomplete attribute:
233

234
```html
235
<!-- Valid input for WebAuthn autofill -->
236
<input type="text" autocomplete="username webauthn" />
237
<input type="email" autocomplete="email webauthn" />
238

239
<!-- These will cause errors -->
240
<input type="text" autocomplete="username" />  <!-- Missing webauthn -->
241
<input type="password" />  <!-- No autocomplete -->
242
```
243

244
The library will automatically check for these inputs unless `verifyBrowserAutofillInput` is set to `false`.