0
# WebAuthn Registration
1

2
WebAuthn registration functionality for creating and registering new authenticators (passkeys, security keys, platform authenticators) with support for automatic registration via password manager integration.
3

4
## Capabilities
5

6
### Start Registration
7

8
Begin authenticator registration via WebAuthn attestation ceremony.
9

10
```typescript { .api }
11
/**
12
 * Begin authenticator "registration" via WebAuthn attestation
13
 * @param options Configuration object containing registration options and settings
14
 * @returns Promise resolving to registration response suitable for server verification
15
 */
16
function startRegistration(options: {
17
  optionsJSON: PublicKeyCredentialCreationOptionsJSON;
18
  useAutoRegister?: boolean;
19
}): Promise<RegistrationResponseJSON>;
20

21
type StartRegistrationOpts = Parameters<typeof startRegistration>[0];
22
```
23

24
**Parameters:**
25

26
- `optionsJSON`: Registration options from your server's `generateRegistrationOptions()` call
27
- `useAutoRegister`: Optional boolean to attempt silent passkey creation with the password manager the user just signed in with (defaults to `false`)
28

29
**Usage Examples:**
30

31
```typescript
32
import { startRegistration } from "@simplewebauthn/browser";
33

34
// Basic registration
35
const registrationOptions = await fetch("/webauthn/register/begin").then(r => r.json());
36

37
try {
38
  const registrationResponse = await startRegistration({
39
    optionsJSON: registrationOptions,
40
  });
41
  
42
  console.log("Registration successful:", registrationResponse);
43
  
44
  // Send to server for verification
45
  const verificationResponse = await fetch("/webauthn/register/finish", {
46
    method: "POST",
47
    headers: { "Content-Type": "application/json" },
48
    body: JSON.stringify(registrationResponse),
49
  });
50
} catch (error) {
51
  console.error("Registration failed:", error);
52
}
53

54
// Auto-registration with password manager
55
try {
56
  const registrationResponse = await startRegistration({
57
    optionsJSON: registrationOptions,
58
    useAutoRegister: true, // Try silent passkey creation
59
  });
60
} catch (error) {
61
  if (error.code === 'ERROR_AUTO_REGISTER_USER_VERIFICATION_FAILURE') {
62
    console.log("Auto-registration failed, user needs manual interaction");
63
  }
64
}
65
```
66

67
### Registration Credential Type
68

69
The raw credential returned from `navigator.credentials.create()`.
70

71
```typescript { .api }
72
interface RegistrationCredential extends PublicKeyCredentialFuture {
73
  response: AuthenticatorAttestationResponseFuture;
74
}
75

76
interface PublicKeyCredentialFuture extends PublicKeyCredential {
77
  type: PublicKeyCredentialType;
78
  isConditionalMediationAvailable?(): Promise<boolean>;
79
  parseCreationOptionsFromJSON?(
80
    options: PublicKeyCredentialCreationOptionsJSON,
81
  ): PublicKeyCredentialCreationOptions;
82
  parseRequestOptionsFromJSON?(
83
    options: PublicKeyCredentialRequestOptionsJSON,
84
  ): PublicKeyCredentialRequestOptions;
85
  toJSON?(): PublicKeyCredentialJSON;
86
}
87

88
interface AuthenticatorAttestationResponseFuture extends AuthenticatorAttestationResponse {
89
  getTransports(): AuthenticatorTransportFuture[];
90
}
91
```
92

93
### Registration Response JSON
94

95
JSON-serializable registration response with Base64URL-encoded ArrayBuffers.
96

97
```typescript { .api }
98
/**
99
 * A slightly-modified RegistrationCredential to simplify working with ArrayBuffers that
100
 * are Base64URL-encoded in the browser so that they can be sent as JSON to the server.
101
 */
102
interface RegistrationResponseJSON {
103
  id: Base64URLString;
104
  rawId: Base64URLString;
105
  response: AuthenticatorAttestationResponseJSON;
106
  authenticatorAttachment?: AuthenticatorAttachment;
107
  clientExtensionResults: AuthenticationExtensionsClientOutputs;
108
  type: PublicKeyCredentialType;
109
}
110

111
interface AuthenticatorAttestationResponseJSON {
112
  clientDataJSON: Base64URLString;
113
  attestationObject: Base64URLString;
114
  // Optional in L2, but becomes required in L3. Play it safe until L3 becomes Recommendation
115
  authenticatorData?: Base64URLString;
116
  // Optional in L2, but becomes required in L3. Play it safe until L3 becomes Recommendation
117
  transports?: AuthenticatorTransportFuture[];
118
  // Optional in L2, but becomes required in L3. Play it safe until L3 becomes Recommendation
119
  publicKeyAlgorithm?: COSEAlgorithmIdentifier;
120
  publicKey?: Base64URLString;
121
}
122
```
123

124
### Registration Options
125

126
Options for WebAuthn registration ceremony.
127

128
```typescript { .api }
129
/**
130
 * A variant of PublicKeyCredentialCreationOptions suitable for JSON transmission to the browser to
131
 * (eventually) get passed into navigator.credentials.create(...) in the browser.
132
 */
133
interface PublicKeyCredentialCreationOptionsJSON {
134
  rp: PublicKeyCredentialRpEntity;
135
  user: PublicKeyCredentialUserEntityJSON;
136
  challenge: Base64URLString;
137
  pubKeyCredParams: PublicKeyCredentialParameters[];
138
  timeout?: number;
139
  excludeCredentials?: PublicKeyCredentialDescriptorJSON[];
140
  authenticatorSelection?: AuthenticatorSelectionCriteria;
141
  hints?: PublicKeyCredentialHint[];
142
  attestation?: AttestationConveyancePreference;
143
  attestationFormats?: AttestationFormat[];
144
  extensions?: AuthenticationExtensionsClientInputs;
145
}
146

147
interface PublicKeyCredentialUserEntityJSON {
148
  id: string;
149
  name: string;
150
  displayName: string;
151
}
152

153
interface PublicKeyCredentialDescriptorJSON {
154
  id: Base64URLString;
155
  type: PublicKeyCredentialType;
156
  transports?: AuthenticatorTransportFuture[];
157
}
158
```
159

160
## Error Handling
161

162
Registration can throw various WebAuthn-specific errors. Common error scenarios:
163

164
- **Browser not supported**: Check with `browserSupportsWebAuthn()` first
165
- **User cancellation**: User cancels the registration prompt
166
- **Authenticator errors**: Hardware issues or unsupported operations
167
- **Invalid options**: Malformed registration options from server
168
- **Duplicate credential**: Attempting to register an already-registered authenticator
169

170
```typescript
171
import { startRegistration, WebAuthnError } from "@simplewebauthn/browser";
172

173
try {
174
  const response = await startRegistration({ optionsJSON });
175
} catch (error) {
176
  if (error instanceof WebAuthnError) {
177
    switch (error.code) {
178
      case 'ERROR_CEREMONY_ABORTED':
179
        console.log("User cancelled registration");
180
        break;
181
      case 'ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED':
182
        console.log("This authenticator is already registered");
183
        break;
184
      case 'ERROR_INVALID_DOMAIN':
185
        console.log("Invalid domain for WebAuthn");
186
        break;
187
      default:
188
        console.log(`Registration error: ${error.code}`);
189
    }
190
  }
191
}
192
```