# 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

Example request in different programming languages:

```javascript
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"
});
```

```python
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"
)
```

## 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
- **publicKeyJsonValue** (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

Example request in different programming languages:

```javascript
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"
});
```

## 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

Example request in different programming languages:

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

## 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

Example request in different programming languages:

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

## 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

Example request in different programming languages:

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

## 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).
- **max_passkeys_per_user** (number): Maximum number of passkeys allowed per user. Defaults to 5, maximum is 10.

Example JSONC configuration:

```json
{
    "hostname": "example.com",
    "max_passkeys_per_user": 5
}
```