# `Playwright.Credentials`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/api/credentials.ex#L7)

[`Credentials`](`Playwright.Credentials`) is a virtual WebAuthn authenticator scoped to a [`BrowserContext`](`Playwright.BrowserContext`). It lets tests
register passkeys and answer `navigator.credentials.create()` / `navigator.credentials.get()`
ceremonies in the page, without a real authenticator or hardware security key.

There are three common ways to use it:

**Usage: seed a known credential**

```elixir
context = Browser.new_context!(browser)

# A passkey your backend already provisioned for a test user.
# All base64url: the private key PKCS#8 (DER), the public key SPKI (DER).
BrowserContext.credentials(context)
|> Credentials.create!("example.com",
  id: known_credential_id,
  user_handle: known_user_handle,
  private_key: known_private_key,
  public_key: known_public_key
)

BrowserContext.credentials(context) |> Credentials.install!()

page = BrowserContext.new_page!(context)
Page.goto!(page, "https://example.com/login")
# The page's navigator.credentials.get() is answered with the seeded passkey.
```

**Usage: capture a credential, then reuse it**

```elixir
# setup test: let the app register a passkey, then save the storage state with it.
context = Browser.new_context!(browser)
BrowserContext.credentials(context) |> Credentials.install!()

page = BrowserContext.new_page!(context)
Page.goto!(page, "https://example.com/register")
Page.get_by_role(page, :button, name: "Create a passkey") |> Locator.click!()

# Read back the passkey the page registered — it includes the private key.
[credential] = BrowserContext.credentials(context) |> Credentials.get!(rp_id: "example.com")
File.write!("playwright/.auth/passkey.json", JSON.encode!(credential))
```

```elixir
# later test: seed the captured passkey so the app starts already enrolled.
credential = File.read!("playwright/.auth/passkey.json") |> JSON.decode!()
context = Browser.new_context!(browser)

BrowserContext.credentials(context)
|> Credentials.create!(credential["rpId"],
  id: credential["id"],
  user_handle: credential["userHandle"],
  private_key: credential["privateKey"],
  public_key: credential["publicKey"],
  sign_count: credential["signCount"]
)

BrowserContext.credentials(context) |> Credentials.install!()

page = BrowserContext.new_page!(context)
Page.goto!(page, "https://example.com/login")
# navigator.credentials.get() resolves the captured passkey — already signed in.
```

**Usage: save credentials in the storage state, restore later**

See [authentication guide](https://playwright.dev/docs/auth) for examples of using saving and restoring the storage state.

**Defaults**

*Since Playwright 1.61.*

The examples alias the modules they use (`alias Playwright.{Locator, Page}`).

# `create_options`

```elixir
@type create_options() ::
  [
    id: String.t(),
    private_key: String.t(),
    public_key: String.t(),
    sign_count: integer(),
    user_handle: String.t()
  ]
  | %{
      optional(:id) =&gt; String.t(),
      optional(:private_key) =&gt; String.t(),
      optional(:public_key) =&gt; String.t(),
      optional(:sign_count) =&gt; integer(),
      optional(:user_handle) =&gt; String.t()
    }
  | %{
      id: String.t(),
      rpId: String.t(),
      userHandle: String.t(),
      privateKey: String.t(),
      publicKey: String.t(),
      signCount: integer()
    }
```

Options of `create/3`, see its docs.

# `get_options`

```elixir
@type get_options() ::
  [id: String.t(), rp_id: String.t()]
  | %{optional(:id) =&gt; String.t(), optional(:rp_id) =&gt; String.t()}
```

Options of `get/2`, see its docs.

# `t`

```elixir
@type t() :: %Playwright.Credentials{_browserContext: term()}
```

A `Credentials` handle. Compare handles with `==`, their fields are internal.

# `create`

```elixir
@spec create(t(), String.t(), create_options()) ::
  {:ok,
   %{
     id: String.t(),
     rpId: String.t(),
     userHandle: String.t(),
     privateKey: String.t(),
     publicKey: String.t(),
     signCount: integer()
   }}
  | {:error, Playwright.error()}
```

Seeds a virtual WebAuthn credential and returns it.

With only `rp_id`, generates a fresh **ECDSA P-256** keypair, credential id and user handle. The
seeded credential is discoverable (resident), so the page can resolve it from both
username-then-passkey and usernameless passkey flows. The returned object carries the private and public keys, so it can be persisted to disk and re-seeded in a later test.

To **import a known credential**, supply all four of `:id`, `:user_handle`, `:private_key` and
`:public_key` together. Pass `:sign_count` as well to continue from the
signature counter the relying party has already seen.

Call `Playwright.Credentials.install/1` before navigating to a page that uses WebAuthn.

In Elixir, the options may also be a result of this function (a map with the JS keys), as JS passes one: `create!(credentials, known.rpId, known)`. Its fields that are no options are ignored.

*Since Playwright 1.61.*

## Arguments

* `rp_id` - Relying party id (typically the site's effective domain).

## Options

* `:id` (`t:String.t/0`) - Base64url-encoded credential id. Auto-generated if omitted.
* `:private_key` (`t:String.t/0`) - Base64url-encoded PKCS#8 (DER) private key. Auto-generated if omitted.
* `:public_key` (`t:String.t/0`) - Base64url-encoded SPKI (DER) public key. Auto-generated if omitted.
* `:sign_count` (`t:integer/0`) - *Since Playwright 1.64.* Initial value of the [signature counter](https://www.w3.org/TR/webauthn-2/#signature-counter). The counter is incremented by one on
  every successful `navigator.credentials.get()` assertion, so the first assertion reports `signCount + 1`. Defaults to `0`.
* `:user_handle` (`t:String.t/0`) - Base64url-encoded user handle. Auto-generated if omitted.

# `create!`

```elixir
@spec create!(t(), String.t(), create_options()) :: %{
  id: String.t(),
  rpId: String.t(),
  userHandle: String.t(),
  privateKey: String.t(),
  publicKey: String.t(),
  signCount: integer()
}
```

Like `create/3`, but returns the value and raises on error.

# `delete`

```elixir
@spec delete(t(), String.t()) :: :ok | {:error, Playwright.error()}
```

Removes a credential from the authenticator by its id. Works for any credential currently held —
both those seeded with `Playwright.Credentials.create/3` and those the page registered itself by
calling `navigator.credentials.create()`.

*Since Playwright 1.61.*

## Arguments

* `id` - Base64url-encoded credential id.

# `delete!`

```elixir
@spec delete!(t(), String.t()) :: :ok
```

Like `delete/2`, but returns the value and raises on error.

# `get`

```elixir
@spec get(t(), get_options()) ::
  {:ok,
   [
     %{
       id: String.t(),
       rpId: String.t(),
       userHandle: String.t(),
       privateKey: String.t(),
       publicKey: String.t(),
       signCount: integer()
     }
   ]}
  | {:error, Playwright.error()}
```

Returns every credential currently held by the authenticator, optionally filtered by `:rp_id` or
`:id`. This includes both credentials seeded with `Playwright.Credentials.create/3` and credentials
the page registered itself by calling `navigator.credentials.create()`.

Each returned credential includes its private and public keys and the current signature counter, so a passkey the app just
registered can be saved and re-seeded into a later test with `Playwright.Credentials.create/3` — see the second example in the class overview.

*Since Playwright 1.61.*

## Options

* `:id` (`t:String.t/0`) - Only return the credential with this base64url-encoded id.
* `:rp_id` (`t:String.t/0`) - Only return credentials for this relying party id.

# `get!`

```elixir
@spec get!(t(), get_options()) :: [
  %{
    id: String.t(),
    rpId: String.t(),
    userHandle: String.t(),
    privateKey: String.t(),
    publicKey: String.t(),
    signCount: integer()
  }
]
```

Like `get/2`, but returns the value and raises on error.

# `install`

```elixir
@spec install(t()) :: :ok | {:error, Playwright.error()}
```

Installs the virtual WebAuthn authenticator into the context, overriding
`navigator.credentials.create()` and `navigator.credentials.get()` in all current
and future pages. Call this before the page first touches `navigator.credentials`.

Required: until `Playwright.Credentials.install/1` is called, no interception is in place and the page sees
the platform's native (or absent) WebAuthn behaviour. Seeding credentials with
`Playwright.Credentials.create/3` without installing populates the authenticator, but the
page will never see those credentials.

*Since Playwright 1.61.*

# `install!`

```elixir
@spec install!(t()) :: :ok
```

Like `install/1`, but returns the value and raises on error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
