Bitwarden Passwordless.dev

https://docs.passwordless.dev/
Admin
Bitwarden Passwordless.dev is a software toolkit that helps developers build FIDO2 WebAuthn-based...
Tokens:36,037
Snippets:379
Trust Score:8.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Passwordless Client Library

Source: https://docs.passwordless.dev/guide/frontend/react.html

Install the necessary client library for passwordless authentication using npm.

```bash
npm install @passwordlessdev/passwordless-client

```

--------------------------------

### Installation

Source: https://docs.passwordless.dev/guide/frontend/javascript

Instructions for installing the Passwordless.dev JavaScript client using yarn, npm, or directly via script tags for ES6 modules or UMD.

```APIDOC
## Installation

Instructions for installing the Passwordless.dev JavaScript client using yarn, npm, or directly via script tags for ES6 modules or UMD.

### Yarn
```bash
yarn add @passwordlessdev/passwordless-client
```

### npm
```bash
npm install @passwordlessdev/passwordless-client
```

### ES6 Module
```html
<script
  src="https://cdn.passwordless.dev/dist/1.1.0/esm/passwordless.min.mjs"
  type="module"
  crossorigin="anonymous"
></script>
```

### UMD
```html
<script
  src="https://cdn.passwordless.dev/dist/1.1.0/umd/passwordless.umd.min.js"
  crossorigin="anonymous"
></script>
```

### Importing the Library

**Yarn/npm:**
```javascript
import { Client } from '@passwordlessdev/passwordless-client';
```

**ES6 Module:**
```html
<script type="module">
  import { Client } from 'https://cdn.passwordless.dev/dist/1.1.0/esm/passwordless.min.mjs';
</script>
```

**UMD:**
```html
<script>
  const Client = Passwordless.Client;
  const p = new Client({});
</script>
```
```

--------------------------------

### Create PasswordlessClient Instance

Source: https://docs.passwordless.dev/guide/backend/python3.html

Instantiate the PasswordlessClient using your API secret. Ensure you have the 'passwordless' package installed.

```python
from passwordless import (
    PasswordlessClient,
    PasswordlessClientBuilder,
    PasswordlessOptions
)


class PasswordlessPythonSdkExample:
    client: PasswordlessClient

    def __init__(self):
        options = PasswordlessOptions("your_api_secret")

        self.client = PasswordlessClientBuilder(options).build()

```

--------------------------------

### Install Passwordless.dev Client with npm

Source: https://docs.passwordless.dev/guide/frontend/javascript

Use this command to add the Passwordless.dev JavaScript client to your project when using npm.

```bash
npm install @passwordlessdev/passwordless-client
```

--------------------------------

### List All Authentication Configurations (HTTP GET)

Source: https://docs.passwordless.dev/guide/api.html

Retrieve a list of all available authentication configurations for the application. This is a simple GET request to the /auth-configs/list endpoint.

```http
GET https://v4.passwordless.dev/auth-configs/list HTTP/1.1

```

--------------------------------

### PasswordlessClient Setup with Dagger Hilt

Source: https://docs.passwordless.dev/guide/frontend/android.html

Inject `PasswordlessClient` using Dagger Hilt by providing `ActivityContext` and `LifecycleCoroutineScope`.

```kotlin
import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.android.components.ActivityComponent
import dagger.hilt.android.qualifiers.ActivityContext
import javax.inject.Scope
import javax.inject.Inject
import kotlinx.coroutines.CoroutineScope
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.LifecycleCoroutineScope
import android.content.Context
import android.app.Activity

@Module
@InstallIn(ActivityComponent::class)
class PasswordlessModule {
    @Provides
    fun provideLifecycleCoroutineScope(activity: Activity): LifecycleCoroutineScope = 
        (activity as AppCompatActivity).lifecycleScope

    @Provides
    @ActivityScoped
    fun providePasswordlessClient(
        @ActivityContext activity: Context, scope: LifecycleCoroutineScope): PasswordlessClient {
        val options = PasswordlessOptions(
            DemoPasswordlessOptions.API_KEY,
            DemoPasswordlessOptions.RP_ID,
            DemoPasswordlessOptions.ORIGIN,
            DemoPasswordlessOptions.API_URL
        )

        return PasswordlessClient(options, activity, scope)
    }
}

```

--------------------------------

### Import Client from @passwordlessdev/passwordless-client (Yarn/npm)

Source: https://docs.passwordless.dev/guide/frontend/javascript

Import the Client class from the Passwordless.dev library after installation via Yarn or npm.

```javascript
import { Client } from '@passwordlessdev/passwordless-client';
```

--------------------------------

### Add Passwordless.AspNetCore NuGet Package

Source: https://docs.passwordless.dev/guide/frontend/aspnet.html

Install the Passwordless ASP.NET Core integration package using the .NET CLI.

```bash
dotnet add package Passwordless.AspNetCore

```

--------------------------------

### Install Passwordless Node.js SDK

Source: https://docs.passwordless.dev/guide/backend/nodejs.html

Install the official Passwordless.dev Node.js SDK using npm. Ensure your Node.js version is 10 or newer and you are using ES2018 or newer.

```bash
$ npm i @passwordlessdev/passwordless-nodejs

```

--------------------------------

### Run Passwordless.dev with SSL and Permanent Storage

Source: https://docs.passwordless.dev/guide/self-hosting/running-locally

This example configures Passwordless.dev for SSL and permanent storage. The admin console is accessible on https://localhost:5042/. After running, register the ssl.crt certificate on your local machine to avoid browser warnings and ensure WebAuthn functionality.

```docker
docker pull bitwarden/passwordless-self-host:stable
docker run \
  --publish 5042:5701 \
  --volume /your/directory:/etc/bitwarden_passwordless \
  --env BWP_PORT=5042 \
  --env BWP_ENABLE_SSL=true \
  bitwarden/passwordless-self-host:stable
```

--------------------------------

### Create Registration Token Request (JavaScript)

Source: https://docs.passwordless.dev/guide/api.html

Initiate a user registration by sending a POST request to the `/register` endpoint. This JavaScript example demonstrates how to construct the payload and headers, including your API private secret. The response contains a token for frontend use.

```javascript
const apiUrl = 'https://v4.passwordless.dev';

const payload = {
  userId: '107fb578-9559-4540-a0e2-f82ad78852f7', // A WebAuthn User Handle, which should be generated by your application. Max. 64 bytes.
  username: 'pjfry@passwordless.dev', // For display purposes, should help a user identify the user account.
  displayname: 'Philip J. Fry', // A human-palatable name for the account.
  authenticatorType: 'any', // WebAuthn authenticator attachment modality. Can be "any" (default), "platform" which triggers client device-specific options Windows Hello, FaceID, or TouchID, or "cross-platform", which triggers roaming options like security keys.
  userVerification: 'preferred', // Whether the relying party requires locally-invoked authorization for the operation. Can be "preferred" (default), "required", or "optional".
  aliases: ['pjfry@passwordless.dev'], // An array of user-created identifiers, like emails, which are used to reference a userId.
  aliasHashing: true // Whether aliases should be hashed before being stored. Defaults to true.
};

// POST the payload to the Passwordless.dev API using your API private secret.
const { token } = await fetch(apiUrl + '/register', {
  method: 'POST',
  body: JSON.stringify(payload),
  headers: {
    'ApiSecret': 'myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4',
    'Content-Type': 'application/json'
  }
}).then((r) => r.json());

```

--------------------------------

### Install Passwordless.dev Client with Yarn

Source: https://docs.passwordless.dev/guide/frontend/javascript

Use this command to add the Passwordless.dev JavaScript client to your project when using Yarn.

```bash
yarn add @passwordlessdev/passwordless-client
```

--------------------------------

### Handle GET Request for Registration Page

Source: https://docs.passwordless.dev/guide/frontend/aspnet.html

This C# code snippet demonstrates the `OnGet` method for the registration page. It redirects authenticated users to the homepage and otherwise returns the page.

```csharp
public IActionResult OnGet()
{
    if (HttpContext.User.Identity is { IsAuthenticated: true })
    {
        return LocalRedirect("/");
    }

    return Page();
}

```

--------------------------------

### Create Registration Token

Source: https://docs.passwordless.dev/guide/backend/dotnet.html

An example of an API endpoint that generates a registration token using the injected `IPasswordlessClient`. It handles potential API exceptions.

```csharp
[HttpGet("/create-token")]
public async Task<IActionResult> GetRegisterToken(string alias)
{
    var userId = Guid.NewGuid().ToString();

    var payload = new RegisterOptions(userId, alias)
    {
        Aliases = new HashSet<string> { alias }
    };

    try
    {
        var token = await _passwordlessClient.CreateRegisterTokenAsync(payload);
        return Ok(token);
    }
    catch (PasswordlessApiException e)
    {
        return new JsonResult(e.Details)
        {
            StatusCode = (int?)e.StatusCode,
        };
    }
}


```

--------------------------------

### Register Token Payload Example

Source: https://docs.passwordless.dev/guide/errors.html

When creating a register token, you must supply a valid userId. This example shows the expected JSON payload structure.

```json
{
  userId: '123',
  username: 'pjfry@passwordless.dev'
}
```

--------------------------------

### Create User Token with Python 2.7+

Source: https://docs.passwordless.dev/guide/backend/python2.html

Use this Python 2.7+ implementation to register a user and create a token for passwordless authentication. Ensure you have the 'requests' and 'simplejson' libraries installed. Replace 'YOUR_API_SECRET' with your actual API secret key.

```python
import requests       # Import the requests library for making HTTP requests
import simplejson as json # Import the simplejson library and alias it as json for working with JSON data
import random        # Import the random library to generate random numbers

# Define the API secret key used for authentication with the remote server
API_SECRET = "YOUR_API_SECRET"

# Function to generate a random integer value
def get_random_int():
  # Multiply a random float (0 to 1) by 1e9 (one billion) and return the integer value
  return int(1e9 * random.random())

# Function to create a token using the given alias
def create_token(alias):
  # Prepare the payload for the API request, including the user ID, username, and aliases
  payload = {
    "userId": get_random_int(),
    "username": alias,
    "aliases": [alias]
  }

  # Convert the payload to a JSON string using simplejson's dumps method
  payload_json = json.dumps(payload)

  # Make a POST request to the specified URL, sending the JSON payload as data, and including headers for the API secret and content type
  response = requests.post("https://v4.passwordless.dev/register/token", data=payload_json, headers={"ApiSecret": API_SECRET, "Content-Type": "application/json"})

  # Load the JSON response content into a Python dictionary using simplejson's loads method
  response_data = json.loads(response.content)

  # Print the response status code, text, and data
  print("passwordless api response", response.status_code, response.text, response_data)

  # Check if the response status code is 200 (Success) and print the received token
  if response.status_code == 200:
    print("received token: ", response_data["token"])
  else:
    # Handle or log any API error
    # Add error handling or logging code here if needed
    pass

  # Return the response data
  return response_data

# Check if the script is being run as the main module
if __name__ == "__main__":
  # Call the create_token function with the alias "alias" and store the response
  response_data = create_token("alias")

```

--------------------------------

### Verify Sign-In Token

Source: https://docs.passwordless.dev/guide/backend/dotnet.html

An example of an API endpoint that verifies a sign-in token using the `IPasswordlessClient`. It returns the verified user information or handles API exceptions.

```csharp
[HttpGet("/verify-signin")]
public async Task<IActionResult> VerifySignInToken(string token)
{
    try
    {
        var verifiedUser = await _passwordlessClient.VerifyTokenAsync(token);
        return Ok(verifiedUser);
    }
    catch (PasswordlessApiException e)
    {
        return new JsonResult(e.Details)
        {
            StatusCode = (int?)e.StatusCode
        };
    }
}


```

--------------------------------

### List User Credentials (HTTP GET)

Source: https://docs.passwordless.dev/guide/api.html

Use this endpoint to list all registered credentials for a given user ID. Requires a GET request to the /credentials/list endpoint with the userId as a query parameter.

```http
GET https://v4.passwordless.dev/credentials/list?userId=107fb578-9559-4540-a0e2-f82ad78852f7 HTTP/1.1
```

--------------------------------

### Defining Routes with Role Protection in App.jsx

Source: https://docs.passwordless.dev/guide/frontend/react.html

Example of how to define routes in your application, including routes that require specific user roles for access using the RequireAuth component.

```javascript
import React, { Component } from 'react';
import { Route, Routes } from 'react-router-dom';
import UserPage from './pages/UserPage';
import AdminPage from './pages/AdminPage';
import PublicPage from './pages/PublicPage';
import Layout from './components/Layout';
import LoginPage from './pages/LoginPage';
import RegisterPage from './pages/RegisterPage';
import RequireAuth from './components/RequireAuth';
import { ROLE_ADMIN, ROLE_USER } from './constants/Roles';
import UnauthorizedPage from './pages/UnauthorizedPage';
import 'react-toastify/dist/ReactToastify.css';

class App extends Component {
  constructor(props) {
    super(props);
  }

  render() {
    return (
      <Layout>
        <Routes>
          <Route exact path="/" element={<PublicPage />} />
          <Route path="/register" element={<RegisterPage />} />
          <Route path="/login" element={<LoginPage />} />
          <Route path="unauthorized" element={<UnauthorizedPage />} />

          <Route element={<RequireAuth allowedRoles={[ROLE_USER]} />}>

```

--------------------------------

### List Specific Authentication Configuration (HTTP GET)

Source: https://docs.passwordless.dev/guide/api.html

Filter the list of authentication configurations by purpose. Append the desired purpose as a query parameter to the /auth-configs/list endpoint.

```http
GET https://v4.passwordless.dev/auth-configs/list?purpose=step-up HTTP/1.1

```

--------------------------------

### Configure Passwordless Services in Startup

Source: https://docs.passwordless.dev/guide/backend/dotnet.html

Configure the Passwordless SDK and options within the `ConfigureServices` method of your `Startup` class. This involves binding configuration settings and registering the SDK with dependency injection.

```csharp
public void ConfigureServices(IServiceCollection services)
{
    // add support for routing to controllers
    services.AddControllers();

    // Inject the Passwordless SDK
    services.Configure<PasswordlessOptions>(Configuration.GetRequiredSection("Passwordless"));
    services.AddPasswordlessSdk(options =>
    {
        Configuration.GetRequiredSection("Passwordless").Bind(options);
    });
}

```

--------------------------------

### Initiate Sign-in on Frontend

Source: https://docs.passwordless.dev/guide/get-started

Use this code on your frontend to initiate the sign-in process by generating an authentication token. Ensure the Client is instantiated with your public API key.

```javascript
// Code written for this step should run on your frontend.

// Instantiate a passwordless client using your API public key.
const p = new Client({
  apiKey: 'myapplication:public:4364b1a49a404b38b843fe3697b803c8'
});

// Allow the user to specify a username or alias.
const alias = 'pjfry@passwordless.dev';

// Generate an authentication token for the user.
const { token, error } = await p.signinWithAlias(alias);
// Tip: You can also try p.signinWithDiscoverable();

// Call your backend to verify the generated token.
const backendUrl = 'https://localhost:7002'; // Your backend.
const verifiedUser = await fetch(backendUrl + '/signin?token=' + token).then((r) => r.json());
if (verifiedUser.success === true) {
  // If successful, proceed!
}

```

--------------------------------

### Passwordless Error Response Example

Source: https://docs.passwordless.dev/guide/frontend/ios

An example of a detailed error response that could be returned from a network request. This structure helps in diagnosing specific issues.

```json
{
  "type": "https://docs.passwordless.dev/errors#missing_register_token",
  "title": "The token you sent was not correct. The token used for this endpoint should start with 'register_'. Make sure you are not sending the wrong value.",
  "status": 400,
  "errorCode": "missing_register_token"
}
```

--------------------------------

### Instantiate Client and Register Passkey

Source: https://docs.passwordless.dev/guide/frontend/javascript

Instantiate the Passwordless client with your API public key and use the .register() method to initiate passkey creation on the user's device after fetching a token from your backend.

```javascript
// Instantiate a passwordless client using your API public key.
const p = new Passwordless.Client({
  apiKey: 'myapplication:public:4364b1a49a404b38b843fe3697b803c8'
});

// Fetch the registration token from the backend.
const backendUrl = 'https://localhost:8002';
const registerToken = await fetch(backendUrl + '/create-token?userId' + userId).then((r) =>
  r.json()
);

// Register the token with the end-user's device.
const { token, error } = await p.register(registerToken);
```

--------------------------------

### Initiate WebAuthn Registration (Frontend)

Source: https://docs.passwordless.dev/guide/get-started

On your frontend, initiate the WebAuthn process to create and store a passkey using the generated registration token. Instantiate a Passwordless client with your API public key and then call the register method.

```javascript
// Code written for this step should run on your frontend.
import { Client } from '@passwordlessdev/passwordless-client';

// Instantiate a passwordless client using your API public key.
const p = new Client({
  apiKey: 'myapplication:public:4364b1a49a404b38b843fe3697b803c8'
});

// Fetch the returned registration token from the backend.
const backendUrl = 'https://localhost:7002'; // Your backend.
const registerToken = await fetch(backendUrl + '/create-user').then((r) => r.json());

// Register the token with the end-user's device.
const { token, error } = await p.register(registerToken);
if (token) {
  // Successfully registered!
} else {
  console.error(error);
}


```

--------------------------------

### Application Entry Point with AuthProvider

Source: https://docs.passwordless.dev/guide/frontend/react.html

Wraps the entire application with AuthProvider to make authentication state globally accessible. Ensure this is placed at the root of your component tree.

```javascript
import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import './index.css';
import App from './App';
import { AuthProvider } from './context/AuthProvider';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <AuthProvider>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </AuthProvider>
  </React.StrictMode>
);
```

--------------------------------

### Instantiate Client with HTML Script Tag

Source: https://docs.passwordless.dev/guide/frontend/javascript

Instantiate the Passwordless.Client when using the UMD version of the library included via a script tag.

```html
<script>
  const Client = Passwordless.Client;
  const p = new Client({});
</script>
```

--------------------------------

### Sign in with User ID

Source: https://docs.passwordless.dev/guide/frontend/javascript

Use .signinWithId(userId) to specify the user for sign-in if their userId is already known, for example, during re-authentication.

```javascript
const userId = '107fb578-9559-4540-a0e2-f82ad78852f7';
const { token, error } = await p.signinWithId(userId);
```

--------------------------------

### Create PasswordlessClient Instance in Java

Source: https://docs.passwordless.dev/guide/backend/java.html

Instantiate the PasswordlessClient with your API secret. Ensure to close the client resources when done.

```java
import com.bitwarden.passwordless.*;

import java.io.*;

public class PasswordlessJavaSdkExample implements Closeable {

    private final PasswordlessClient client;

    public PasswordlessJavaSdkExample() {
        PasswordlessOptions options = PasswordlessOptions.builder()
                .apiSecret("your_api_secret")
                .build();

        client = PasswordlessClientBuilder.create(options)
                .build();
    }

    @Override
    public void close() throws IOException {
        client.close();
    }
}

```

--------------------------------

### Get Debug Keystore Fingerprint

Source: https://docs.passwordless.dev/guide/frontend/android.html

Use the keytool command to list details of your debug keystore, including the SHA-256 certificate fingerprint.

```bash
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
```

```powershell
keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android
```

--------------------------------

### Sign in with Alias

Source: https://docs.passwordless.dev/guide/frontend/ios

Initiate the sign-in process using an alias (e.g., username) by calling `signIn(alias:)`. This presents a passkey selection modal to the user and returns a verification token upon successful authentication.

```swift
let verifyToken = try await passwordlessClient.signIn(alias: username)
```

--------------------------------

### Successful Sign-in Verification Response

Source: https://docs.passwordless.dev/guide/get-started

This is an example of a successful response from the Passwordless.dev API's /signin/verify endpoint, indicating a verified user.

```json
{
  "success": true,
  "userId": "123",
  "timestamp": "2021-08-01T01:33:36.9773187Z",
  "rpid": "example.com",
  "origin": "http://example.com:3000",
  "device": "Chrome, Windows 10",
  "country": "",
  "nickname": "Home laptop",
  "credentialId": "Mq1ZhrHBmhly34YaO/uuXuNuf/VCHDkuknENz/LZJR4=",
  "expiresAt": "2021-08-01T01:35:36.9773193Z"
}

```

--------------------------------

### Register User

Source: https://docs.passwordless.dev/guide/frontend/javascript

Use the `.register()` method to obtain a registration token from your backend, which authorizes the creation of a passkey on the user's device.

```APIDOC
## .register()

Call the `.register()` method to fetch a registration token from your backend to authorize creation of a passkey on the end-user's device.

### Request Example
```javascript
// Instantiate a passwordless client using your API public key.
const p = new Passwordless.Client({
  apiKey: 'myapplication:public:4364b1a49a404b38b843fe3697b803c8'
});

// Fetch the registration token from the backend.
const backendUrl = 'https://localhost:8002';
const registerToken = await fetch(backendUrl + '/create-token?userId' + userId).then((r) =>
  r.json()
);

// Register the token with the end-user's device.
const { token, error } = await p.register(registerToken);
```

### Description
Successful implementation will prompt Passwordless.dev to negotiate creation of a passkey through the user's web browser API and save its public key to the database for future sign-in operations.
```

--------------------------------

### Initialize PasswordlessClient

Source: https://docs.passwordless.dev/guide/frontend/ios

Initialize the PasswordlessClient with your API key and relying party ID. The relying party ID should match the domain hosting your apple-app-site-association file.

```swift
let passwordlessClient = PasswordlessClient(
    config: PasswordlessConfig(
        apiKey: "<YOUR API KEY>",
        rpId: "demo.passwordless.dev"
    )
)
```

--------------------------------

### Redirect Authenticated Users in Razor Page

Source: https://docs.passwordless.dev/guide/frontend/aspnet.html

This C# code snippet handles the GET request for the login page. If the user is already authenticated, it redirects them to the root path; otherwise, it proceeds to display the page.

```csharp
public IActionResult OnGet()
{
    if (HttpContext.User.Identity is { IsAuthenticated: true })
    {
        return LocalRedirect("/");
    }
    return Page();
}
```

--------------------------------

### Sign In Methods

Source: https://docs.passwordless.dev/guide/frontend/javascript

Provides methods to generate an authentication token for backend verification, supporting autofill, discoverable passkeys, alias, and user ID.

```APIDOC
## .signinWith()

Call the `.signin` methods to generate an authentication token that will be checked by your backend to complete a sign-in. There are a few different `.signinWith*()` methods available:

| Method | Description | Example |
|---|---|---|
| `.signinWithAutofill()` | Triggers the Browser native autofill UI to select identity and sign in. | `verify_token = await p.signinWithAutofill();` |
| `.signinWithDiscoverable()` | Triggers the Browsers native UI prompt to select identity and sign in. | `verify_token = await p.signinWithDiscoverable();` |
| `.signinWithAlias(alias)` | Uses a alias (e.g. email,username) to specify the user. | `verify_token = await p.signinWithAlias(email);` |
| `.signinWithId(id)` | Uses the userId to specify the user. | `verify_token = await p.signinWithId(userId);` |

### Request Example
```javascript
// Instantiate a passwordless client using your API public key.
const p = new Passwordless.Client({
  apiKey: 'myapplication:public:4364b1a49a404b38b843fe3697b803c8'
});

// Generate an authentication token for the user.

// Option 1: Enable browsers to suggest passkeys for any input that has autofill="webauthn" (only works with discoverable passkeys).
const { token, error } = await p.signinWithAutofill();

// Option 2: Enables browsers to suggest passkeys by opening a UI prompt (only works with discoverable passkeys).
const { token, error } = await p.signinWithDiscoverable();

// Option 3: Use an alias specified by the user.
const email = 'pjfry@passwordless.dev';
const { token, error } = await p.signinWithAlias(email);

// Option 4: Use a userId if already known, for example if the user is re-authenticating.
const userId = '107fb578-9559-4540-a0e2-f82ad78852f7';
const { token, error } = await p.signinWithId(userId);

if (error) {
  console.error(error);
  // { errorCode: "unknown_credential", "title": "That credential is not registered with this website", "details": "..."}
}

// Call your backend to verify the token.
const backendUrl = 'https://localhost:8002'; // Your backend
const verifiedUser = await fetch(backendUrl + '/signin?token=' + token).then((r) => r.json());
if (verifiedUser.success === true) {
  // If successful, proceed!
  // verifiedUser.userId = "107fb578-9559-4540-a0e2-f82ad78852f7";
}
```

### Response
All `.signinWith*()` methods return a object with two properties, commonly destructured as:
```javascript
// destructured
const { token, error } = await p.siginWithId(123);

// plain object
const signinResponse = await p.signinWithId(123);
console.log(signinResponse.token); // "verify_xxyyzz"
console.error(response.error); // undefined or a problem details object
```

If the signin was successful, the `token` has a string value `"verify_xxyyzz"`. If the sign-in failed, the `error` property contains the problem details.
```

--------------------------------

### Generate Authentication Token (JavaScript)

Source: https://docs.passwordless.dev/guide/api.html

Use `fetch` to POST a `userId` and `timeToLive` to the `/signin/generate-token` endpoint. The `timeToLive` parameter defaults to 120 seconds if not specified.

```javascript
const apiUrl = 'https://v4.passwordless.dev';

// Generate an authentication token, side-stepping the usual signin process.
const payload = {
  userId: '107fb578-9559-4540-a0e2-f82ad78852f7', // ID of the user to generate the token for.
  timeToLive: 30 // Time in seconds the token is valid for. Default is 120 seconds.
};

// POST the user ID to the Passwordless.dev API using your API private secret.
const response = await fetch(apiUrl + '/signin/generate-token', {
  method: 'POST',
  body: JSON.stringify(payload),
  headers: {
    'ApiSecret': 'myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4',
    'Content-Type': 'application/json'
  }
});

```

--------------------------------

### Create Passwordless.dev Token in PHP

Source: https://docs.passwordless.dev/guide/backend/php

This function generates a user ID, prepares a payload with user information and aliases, and sends a POST request to the Passwordless.dev API to create an authentication token. It requires the API secret key for authentication and uses cURL for the HTTP request. Ensure the curl library is enabled in your PHP installation.

```PHP
<?php

// Define the API secret key used for authentication with the remote server
$API_SECRET = "YOUR_API_SECRET";

// Function to generate a random integer value
function get_random_int() {
  // Multiply the random number generated by mt_rand() by 1e9 (one billion) and return the integer value
  return intval(1e9 * mt_rand());
}

// Function to create a token using the given alias
function create_token($alias) {
  global $API_SECRET; // Make the API secret accessible inside the function

  // Prepare the payload for the API request, including the user ID, username, and aliases
  $payload = array(
    "userId" => get_random_int(),
    "username" => $alias,
    "aliases" => array($alias)
  );

  // Initialize a cURL session
  $ch = curl_init();
  // Set the URL of the remote server
  curl_setopt($ch, CURLOPT_URL, "https://v4.passwordless.dev/register/token");
  // Indicate that this is a POST request
  curl_setopt($ch, CURLOPT_POST, 1);
  // Attach the JSON-encoded payload as the POST data
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  // Set the HTTP headers, including the API secret and content type
  curl_setopt($ch, CURLOPT_HTTPHEADER, array("ApiSecret: $API_SECRET", "Content-Type: application/json"));
  // Return the response as a string instead of printing it
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  // Optionally, disable SSL certificate verification (not recommended for production)
  // curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  // Execute the cURL request and store the response
  $response = curl_exec($ch);

  // Check for cURL errors and print them if any
  if (curl_errno($ch)) {
      print("cURL error: " . curl_error($ch) . "\n");
  }

  // Get the HTTP response code
  $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  // Close the cURL session
  curl_close($ch);

  // Print the API response code
  print("passwordless api response: " . $response_code . "\n");

  // Decode the JSON response into an associative array
  $response_data = json_decode($response, true);
  print_r($response_data);

  // Check if the response code is 200 (Success) and print the received token
  if ($response_code == 200) {
    print("received token: " . $response_data["token"] . "\n");
  } else {
    // Handle or log any API error
    // Log or handle the error as needed in this block
  }

  // Return the response data
  return $response_data;
}

// Check if the script is executed with exactly one argument
if ($argc == 2) {
  // Get the alias from the command-line argument
  $alias = $argv[1];
  // Call the create_token function with the alias and store the response
  $response_data = create_token($alias);
} else {
  // Print the usage instruction if the script is not executed with the correct number of arguments
  print("Usage: create_token.php <alias>\n");
}
?>

```

--------------------------------

### Initialize Passwordless.dev Client with UMD Script

Source: https://docs.passwordless.dev/guide/get-started

Initialize the Passwordless.dev Client after including the UMD script. The Client constructor can be called with an empty object if no specific configuration is needed initially.

```javascript
const Client = Passwordless.Client;
const p = new Client({});
```

--------------------------------

### Check Platform Support for Passkeys

Source: https://docs.passwordless.dev/guide/frontend/javascript

Use the async `.isPlatformSupported()` method to check if the user's device or browser supports platform authentication like Windows Hello. This is an asynchronous check.

```javascript
if (await Passwordless.isPlatformSupported()) {
}
```

--------------------------------

### List Authentication Configurations

Source: https://docs.passwordless.dev/guide/api.html

Retrieves a list of all existing authentication configurations.

```APIDOC
## GET /auth-configs/list

### Description
Retrieves a list of all existing authentication configurations.

### Method
GET

### Endpoint
/auth-configs/list

### Response
#### Success Response (200)
- **configurations** (array) - A list of authentication configuration objects.
  - **purpose** (string) - The purpose of the authentication configuration.
  - **timeToLive** (integer) - The time-to-live for the configuration in seconds.
  - **userVerificationRequirement** (string) - The requirement for user verification ('preferred', 'required', 'discouraged').
  - **createdBy** (string) - Identifier of the user who created the configuration.
  - **createdOn** (string) - Timestamp of when the configuration was created.
  - **editedBy** (string) - Identifier of the user who last edited the configuration.
  - **editedOn** (string) - Timestamp of when the configuration was last edited.
  - **lastUsedOn** (string) - Timestamp of when the configuration was last used.

#### Response Example
```json
{
  "configurations": [
    {
      "purpose": "sign-in",
      "timeToLive": 120,
      "userVerificationRequirement": "preferred",
      "createdBy": "System",
      "createdOn": null,
      "editedBy": null,
      "editedOn": null,
      "lastUsedOn": null
    },
    {
      "purpose": "step-up",
      "timeToLive": 180,
      "userVerificationRequirement": "required",
      "createdBy": "System",
      "createdOn": null,
      "editedBy": null,
      "editedOn": null,
      "lastUsedOn": null
    }
  ]
}
```
```

--------------------------------

### PasswordlessClient Login

Source: https://docs.passwordless.dev/guide/frontend/android.html

Initiate the login process with an optional alias using `PasswordlessClient.login()`. After a successful response, verify the token with your backend.

```kotlin
// Call PasswordlessClient.login() with the alias
_passwordless.login(alias) { success, exception, result ->
    if (success) {
        lifecycleScope.launch {
            // When successful, call your backend to verify the token, which could for example return a JWT token.
            val clientDataResponse = httpClient.login(UserLoginRequest(result?.token!!))
            if (clientDataResponse.isSuccessful) {
                // Login successful. Parse the response or JWT token and proceed.
                val data = clientDataResponse.body()
                showText(data.toString())
            }
        }
    } else {
        showException(exception)
    }
}

```

--------------------------------

### PasswordlessClient Registration

Source: https://docs.passwordless.dev/guide/frontend/android.html

Initiate the registration process by passing the generated registration token and an optional nickname to `PasswordlessClient.register()`.

```kotlin
// Pass the registration token to PasswordlessClient.register()
_passwordless.register(
    token = responseToken,
    nickname = nickname
) { success, exception, result ->
    if (success) {
        Toast.makeText(context, result.toString(), Toast.LENGTH_SHORT).show()
    } else {
        Toast.makeText(context, "Exception: " + getPasskeyFailureMessage(exception as Exception), Toast.LENGTH_SHORT).show()
    }
}

```

--------------------------------

### List Authentication Configurations

Source: https://docs.passwordless.dev/guide/api.html

Retrieve a list of all existing authentication configurations. The response includes details such as purpose, time-to-live, and verification requirements.

```json
{
  "configurations": [
    {
      "purpose": "sign-in",
      "timeToLive": 120,
      "userVerificationRequirement": "preferred",
      "createdBy": "System",
      "createdOn": null,
      "editedBy": null,
      "editedOn": null,
      "lastUsedOn": null
    },
    {
      "purpose": "step-up",
      "timeToLive": 180,
      "userVerificationRequirement": "required",
      "createdBy": "System",
      "createdOn": null,
      "editedBy": null,
      "editedOn": null,
      "lastUsedOn": null
    }
  ]
}
```

--------------------------------

### Initiate Step-Up Authentication

Source: https://docs.passwordless.dev/guide/frontend/javascript

The `.stepup()` method allows for a specific purpose to be passed for authentication verification, similar to `.signin()`. The response contains either a `token` on success or an `error` object on failure.

```javascript
const stepUpRequest = {
  signinMethod: {
    userId: 123 // you could also use alias as the signinMethod as well.
  },
  purpose: 'step-up'
};

// destructured
const { token, error } = await p.stepup(stepUpRequest);

// plain object
const response = await p.stepup(stepUpRequest);
console.log(response.token); // verify_xxyyzz
console.error(response.error); // undefined or a problem details object
```

--------------------------------

### Register a Passkey with Passwordless.dev in Java

Source: https://docs.passwordless.dev/guide/backend/java.html

Generate a registration token for a new user, optionally linking it to provided aliases. This token is used to initiate the passkey registration process.

```java
import com.bitwarden.passwordless.*;
import com.bitwarden.passwordless.error.*;
import com.bitwarden.passwordless.model.*;

import java.io.*;
import java.util.*;

public class PasswordlessJavaSdkExample {

    private final PasswordlessClient client;

    // Constructor

    public String getRegisterToken(String alias) throws PasswordlessApiException, IOException {

        // Get existing userid from session or create a new user.
        String userId = UUID.randomUUID().toString();

        // Options to give the Api
        RegisterToken registerToken = RegisterToken.builder()
                // your user id
                .userId(userId)
                // e.g. user email, is shown in browser ui
                .username(alias)
                // Optional: Link this userid to an alias (e.g. email)
                .aliases(Arrays.asList(alias))
                .build();

        RegisteredToken response = client.registerToken(registerToken);

        // return this token
        return response.getToken();
    }
}

```

--------------------------------

### Add Authentication Configuration

Source: https://docs.passwordless.dev/guide/api.html

Creates a new authentication configuration.

```APIDOC
## POST /auth-configs/add

### Description
Creates a new authentication configuration for the authentication process.

### Method
POST

### Endpoint
/auth-configs/add

### Parameters
#### Request Body
- **purpose** (string) - Required - Identifying string with A-z, 0-9, -, and _ allowed characters. Max length of 255 characters.
- **timeToLive** (string) - Required - Positive time span value in hh:mm:ss format.
- **userVerificationRequirement** (string) - Required - Must be one of 'preferred', 'required', or 'discouraged'.
- **performedBy** (string) - Required - User identifier to track changes to the configuration.

### Request Example
```json
{
  "purpose": "access-secrets-purpose",
  "timeToLive": "00:03:00",
  "userVerificationRequirement": "preferred",
  "performedBy": "user_123"
}
```

### Response
#### Success Response (201)
HTTP 201 (Created) status code.

#### Error Response (400)
HTTP 400 (Bad Request) status code with a problem details body.
```

--------------------------------

### Complete Sign-in Flow

Source: https://docs.passwordless.dev/guide/frontend/javascript

After obtaining a token from a .signinWith*() method, send it to your backend for verification. The backend should then return user information if the sign-in is successful.

```javascript
// Instantiate a passwordless client using your API public key.
const p = new Passwordless.Client({
  apiKey: 'myapplication:public:4364b1a49a404b38b843fe3697b803c8'
});

// Generate an authentication token for the user.

// Option 1: Enable browsers to suggest passkeys for any input that has autofill="webauthn" (only works with discoverable passkeys).
const { token, error } = await p.signinWithAutofill();

// Option 2: Enables browsers to suggest passkeys by opening a UI prompt (only works with discoverable passkeys).
const { token, error } = await p.signinWithDiscoverable();

// Option 3: Use an alias specified by the user.
const email = 'pjfry@passwordless.dev';
const { token, error } = await p.signinWithAlias(email);

// Option 4: Use a userId if already known, for example if the user is re-authenticating.
const userId = '107fb578-9559-4540-a0e2-f82ad78852f7';
const { token, error } = await p.signinWithId(userId);

if (error) {
  console.error(error);
  // { errorCode: "unknown_credential", "title": "That credential is not registered with this website", "details": "..."}
}

// Call your backend to verify the token.
const backendUrl = 'https://localhost:8002'; // Your backend
const verifiedUser = await fetch(backendUrl + '/signin?token=' + token).then((r) => r.json());
if (verifiedUser.success === true) {
  // If successful, proceed!
  // verifiedUser.userId = "107fb578-9559-4540-a0e2-f82ad78852f7";
}
```

--------------------------------

### Verify Authentication Token (JavaScript)

Source: https://docs.passwordless.dev/guide/api.html

Use `fetch` to send a POST request to the `/signin/verify` endpoint with the authentication token. Ensure your API secret is included in the headers.

```javascript
const apiUrl = 'https://v4.passwordless.dev';

// Fetch the authentication token from your frontend.
const payload = { token: req.query.token };

// POST the authentication token to the Passwordless.dev API using your API private secret.
const response = await fetch(apiUrl + '/signin/verify', {
  method: 'POST',
  body: JSON.stringify(payload),
  headers: {
    'ApiSecret': 'myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4',
    'Content-Type': 'application/json'
  }
});

```

--------------------------------

### Register Passkey

Source: https://docs.passwordless.dev/guide/frontend/ios

Initiate the passkey registration process by calling `register(token:)` with a registration token obtained from your backend. This prompts the user for biometric authentication and returns a verification token upon success.

```swift
let verifyToken = try await passwordlessClient.register(token: registrationToken)
```

--------------------------------

### Initialize Passwordless Client with Default Base URL

Source: https://docs.passwordless.dev/guide/backend/nodejs.html

Initialize the Passwordless client using the default base URL. Your ApiSecret can be found in the Passwordless.dev admin console.

```typescript
const options: PasswordlessOptions = {};
this._passwordlessClient = new PasswordlessClient(
  'demo:secret:f831e39c29e64b77aba547478a4b3ec6',
  options
);

```

--------------------------------

### Initialize Passwordless Client with Base URL

Source: https://docs.passwordless.dev/guide/backend/nodejs.html

Initialize the Passwordless client specifying a custom base URL. Your ApiSecret can be found in the Passwordless.dev admin console.

```typescript
const options: PasswordlessOptions = {
  baseUrl: 'https://v4.passwordless.dev'
};
this._passwordlessClient = new PasswordlessClient(
  'demo:secret:f831e39c29e64b77aba547478a4b3ec6',
  options
);

```

--------------------------------

### Run Passwordless.dev with Permanent Storage

Source: https://docs.passwordless.dev/guide/self-hosting/running-locally

This command runs Passwordless.dev with permanent storage, retaining configuration and SQLite databases on the host. The admin console is accessible on http://localhost:5042/.

```docker
docker pull bitwarden/passwordless-self-host:stable
docker run \
  --publish 5042:5701 \
  --volume /your/directory:/etc/bitwarden_passwordless \
  --env BWP_PORT=5042 \
  bitwarden/passwordless-self-host:stable
```

--------------------------------

### Add Authentication Configuration

Source: https://docs.passwordless.dev/guide/api.html

Create a new authentication configuration. Ensure the `purpose` adheres to A-z, 0-9, -, and _ characters with a maximum length of 255. `timeToLive` must be a positive time span in hh:mm:ss format.

```http
GET https://v4.passwordless.dev/auth-configs/add HTTP/1.1



{
  "purpose": "access-secrets-purpose", // identifying string give context to the specific authentication
  "timeToLive": "00:03:00", // timespan the token is valid for
  "userVerificationRequirement": "preferred", // requirement for if the user has to verify they're allowed to use an authenticator
  "performedBy": "user_123" // user identifier to track changes to the configuration
}
```

--------------------------------

### Verify Authentication Token

Source: https://docs.passwordless.dev/guide/api.html

Send a POST request to `/signin/verify` with an authentication token to verify its legitimacy. The token should be obtained from a frontend `.signinWith*()` method.

```http
POST https://v4.passwordless.dev/signin/verify HTTP/1.1



{
  "token": "d5vzCkL_GvpS4VYtoT3..."
}
```

--------------------------------

### Import Client from CDN (ES6 Module)

Source: https://docs.passwordless.dev/guide/frontend/javascript

Import the Client class directly from the Passwordless.dev CDN when using ES6 modules.

```html
<script type="module">
  import { Client } from 'https://cdn.passwordless.dev/dist/1.1.0/esm/passwordless.min.mjs';
</script>
```

--------------------------------

### File Email Provider Environment Variables

Source: https://docs.passwordless.dev/guide/self-hosting/configuration.html

Configure the file email provider using environment variables. An optional path can be specified for where emails will be stored.

```bash
-e Mail__Providers__#__Name='file'
-e Mail__Providers__#__Path='/path/on/your/machine' #(optional)
```
Tokens:
Raw