.. _org.freedesktop.impl.portal.experimental.Credential:

===================================================
 Credential   🧪
===================================================

-----------
Description
-----------

.. _org.freedesktop.impl.portal.experimental.Credential Description:

Credential portal backend interface

**Interface**: ``org.freedesktop.impl.portal.experimental.Credential``

**Version**: Experimental 🧪

The Credential portal allows sandboxed applications to retrieve
application-scoped web credentials. The backend interface guides the user
through the interactive authentication ceremony.



.. _org.freedesktop.impl.portal.experimental.Credential Properties:

----------
Properties
----------

.. _org.freedesktop.impl.portal.experimental.Credential:version:

org.freedesktop.impl.portal.experimental.Credential:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.impl.portal.experimental.Credential Methods:

-------
Methods
-------

.. _org.freedesktop.impl.portal.experimental.Credential.CreateSession:

org.freedesktop.impl.portal.experimental.Credential.CreateSession
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CreateSession (
      IN session_handle o,
      IN parent_window s,
      IN origin s,
      IN type u,
      IN sources a(ss),
      IN app_id s,
      IN app_pid u,
      IN options a{sv}
    )



Creates a session for an authentication ceremony with the client context
and an initial list of credential sources. During the ceremony, the
backend sends user interaction events to the frontend via signals in
response to background events sent from the frontend via the other
methods on this interface.

Before calling this method, the frontend MUST subscribe to all
signals on this interface, filtering for the given ``session_handle``
argument. A :ref:`org.freedesktop.impl.portal.Session` object will be
exported on the ``session_handle`` path, which can be used by the frontend
to cancel the ceremony or receive notification that the
user cancelled it. Frontends MUST use the same D-Bus connection
throughout the ceremony.

Upon receiving this method call, backends MUST send
:ref:`org.freedesktop.impl.portal.experimental.Credential::DiscoveryRequested`
when the user is ready to perform the authentication ceremony.
Backends MUST send all signals as unicast signals to the original sender
calling this method.

Supported keys in the ``options`` vardict include:

* ``activation_token`` (``s``)

  A token that can be used to activate the credential selection dialog.

* ``top_origin`` (``s``)

  Top-level origin of the request if different from the origin.

* ``rp_id`` (``s``)

  WebAuthn relying party ID.

  Required if ``type`` is ``PublicKeyCreate`` or ``PublicKeyGet``.



session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` to create.

parent_window
  Identifier for the application window, see :doc:`window-identifiers`.

origin
  The origin of the request.

type
  Type of the credential to create. Current supported types are ``PublicKeyCreate = 0``, and ``PublicKeyGet = 1``.

sources
  Initial list of credential sources. Map from source ID to transport. Valid transports are ``Ble``, ``HybridLinked``, ``HybridQr``, ``Internal``, ``Nfc``, ``Usb``. Sources may be added or removed during the ceremony.

app_id
  App ID of the application.

app_pid
  PID of the application.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsPin:

org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsPin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyNeedsPin (
      IN session_handle o,
      IN attempts_left u,
      IN options a{sv}
    )



The device needs PIN user verification: prompt the user to enter the
PIN. The backend must emit the collected value as a
:ref:`org.freedesktop.impl.portal.experimental.Credential::ClientPinEntered`
signal. See the documentation on that signal for PIN requirements.

The backend should consider rate-limiting requests, or requiring the
user to power-cycle (e.g., unplug and plug back in) the device after
repeated incorrect attempts to prevent the device from being locked out
due to user error or abuse.

The backend should warn the user that the credentials may be permanently
lost if they continue to enter incorrect PINs.

There are currently no supported keys in the ``options`` vardict.

.. seealso::
   * `CTAP 2.3 documentation on PIN and user verification retries`_



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

attempts_left
  The number of PIN attempts remaining before the device is locked out and must be reset/wiped. ``0xffffffff`` means the number of attempts left is unknown.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsUserVerification:

org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsUserVerification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyNeedsUserVerification (
      IN session_handle o,
      IN attempts_left u,
      IN options a{sv}
    )



The authenticator needs on-device user verification (likely biometrics, or
can be on-device PIN entry). Prompt the user to interact with the
device.

The backend should display the number of built-in user verification
attempts remaining before falling back to client PIN verification.

.. note::

   This is distinct from
   :ref:`org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsPin`,
   which uses a PIN captured on the client device rather than directly
   on the authenticator.

There are currently no supported keys in the ``options`` vardict.

.. seealso::
   * `CTAP 2.3 documentation on PIN and user verification retries`_

.. _CTAP 2.3 documentation on PIN and user verification retries: https://fidoalliance.org/specs/fido-v2.3-ps-20260226/fido-client-to-authenticator-protocol-v2.3-ps-20260226.html#authnrClientPin-globalState-retries



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

attempts_left
  The number of user verification attempts remaining before the built-in user verification methods are disabled until the next successful PIN verification. ``0xffffffff`` means the number of attempts left is unknown.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsUserPresence:

org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsUserPresence
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyNeedsUserPresence (
      IN session_handle o,
      IN options a{sv}
    )



Device requires user interaction (e.g. pressing a button) to release credentials; prompt the user
to do so. The device may require additional user verification, but that
might not be known until after the user taps the device.

There are currently no supported keys in the ``options`` vardict.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifySelectingCredential:

org.freedesktop.impl.portal.experimental.Credential.NotifySelectingCredential
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifySelectingCredential (
      IN session_handle o,
      IN credentials aa{sv},
      IN options a{sv}
    )



The device is ready to release credentials, but multiple credentials
match the request. The backend must prompt the user to select one of the
credentials.

Each metadata object in ``credentials`` contains the following fields:

* ``id``: An opaque value to send back to the authenticator. It is NOT the WebAuthn ``credentialId``.
* ``name``: The account name for the credential.
* ``display_name``: The human-readable username for the credential.

There are currently no supported keys in the ``options`` vardict.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

credentials
  A list of metadata for credentials that are able to fulfill the request.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyHybridStarted:

org.freedesktop.impl.portal.experimental.Credential.NotifyHybridStarted
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyHybridStarted (
      IN session_handle o,
      IN invocation_data h,
      IN options a{sv}
    )



Hybrid discovery is activated and is awaiting an invocation on the peer
device. The backend MUST display the ``invocation_data`` as a QR code. For
public key credentials (where ``type`` of
:ref:`org.freedesktop.impl.portal.experimental.Credential.CreateSession`
is set to ``PublicKeyCreate`` or ``PublicKeyGet``), the backend SHOULD
overlay the FIDO passkey logo on the QR code.

The backend MAY use other invocation methods besides QR code as the CTAP2 spec evolves.

``invocation_data`` is a file descriptor whose data consists of the UTF-8-encoded PIN. The file
must be memory-mapped to be read. Call ``fstat()`` to determine the length of the data.

There are currently no supported keys in the ``options`` vardict.

.. seealso::
   * `CTAP 2.3 Hybrid Transport documentation`_
   * `FIDO Alliance Logos`_

.. _CTAP 2.3 Hybrid Transport documentation: https://fidoalliance.org/specs/fido-v2.3-ps-20260226/fido-client-to-authenticator-protocol-v2.3-ps-20260226.html#sctn-hybrid
.. _FIDO Alliance Logos: https://fidoalliance.org/overview/legal/



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

invocation_data
  A memory-mapped filed containing a string of data that is used to invoke the hybrid flow on the peer device.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyHybridConnecting:

org.freedesktop.impl.portal.experimental.Credential.NotifyHybridConnecting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyHybridConnecting (
      IN session_handle o,
      IN options a{sv}
    )



The other device has been detected, and a connection is being
established. The backend should communicate a pending status and prompt
the user to keep the devices close.

There are currently no supported keys in the ``options`` vardict.

.. seealso::
   * `CTAP 2.3 Hybrid Transport documentation`_



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyHybridConnected:

org.freedesktop.impl.portal.experimental.Credential.NotifyHybridConnected
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyHybridConnected (
      IN session_handle o,
      IN options a{sv}
    )



A connection has been established, waiting for user to release
credential on their device. The backend should prompt the user to follow
the instructions on the peer device.

There are currently no supported keys in the ``options`` vardict.

.. seealso::
   * `CTAP 2.3 Hybrid Transport documentation`_



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyNfcConnected:

org.freedesktop.impl.portal.experimental.Credential.NotifyNfcConnected
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyNfcConnected (
      IN session_handle o,
      IN options a{sv}
    )



An NFC device has been detected. The backend should prompt the user to
keep the peer device on the NFC reader so that the ceremony can
complete.

There are currently no supported keys in the ``options`` vardict.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyUsbConnected:

org.freedesktop.impl.portal.experimental.Credential.NotifyUsbConnected
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyUsbConnected (
      IN session_handle o,
      IN options a{sv}
    )



USB device connected, prompt user to interact with the device (e.g.
press the button).

The device may require additional user verification to complete the
ceremony, but that might not be known until after the user taps the
device.

There are currently no supported keys in the ``options`` vardict.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

options
  Vardict with optional further information.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyCeremonyCompleted:

org.freedesktop.impl.portal.experimental.Credential.NotifyCeremonyCompleted
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyCeremonyCompleted (
      IN session_handle o
    )



The frontend should call this method when the ceremony completes
successfully, and the dialog can be closed.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.


Method available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential.NotifyErrorOccurred:

org.freedesktop.impl.portal.experimental.Credential.NotifyErrorOccurred
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    NotifyErrorOccurred (
      IN session_handle o,
      IN error u
    )



Notify the backend that an error occurred.

``error`` may contain the following values:

* ``ERROR_AUTHENTICATOR = 0x80000001``

  An unknown authenticator error occurred.

* ``ERROR_NO_CREDENTIALS = 0x80000002``

  The authenticator reported that it has no matching credentials stored.

* ``ERROR_PIN_ATTEMPTS_EXHAUSTED = 0x80000003``

  Too many PIN attempts have been entered, and the authenticator is
  permanently locked out and must be reset.

* ``ERROR_INTERNAL = 0x80000004``

  An internal portal error occurred.

* ``ERROR_TIMED_OUT = 0x80000005``

  The credential request has timed out.

* ``ERROR_CANCELLED = 0x80000006``

  The user cancelled the request.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

error
  The error that occurred.


Method available since: 1.

.. _org.freedesktop.impl.portal.experimental.Credential Signals:

-------
Signals
-------

.. _org.freedesktop.impl.portal.experimental.Credential::DiscoveryRequested:

org.freedesktop.impl.portal.experimental.Credential::DiscoveryRequested
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    DiscoveryRequested (
      session_handle o,
      options a{sv}
    )



Request for the platform to start credential discovery. This should be
emitted by the backend after
:ref:`org.freedesktop.impl.portal.experimental.Credential.CreateSession`
is called, when all signals are subscribed and the user is ready to
perform the authentication ceremony.

There are currently no supported keys in the ``options`` vardict.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

options
  Vardict with optional further information.


Signal available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential::ClientPinEntered:

org.freedesktop.impl.portal.experimental.Credential::ClientPinEntered
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ClientPinEntered (
      session_handle o,
      pin_fd h,
      options a{sv}
    )



Sends the client PIN to the authenticator for user verification via
``pin_fd`` in response to
:ref:`org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsPin`.

This is a file descriptor whose data consists of the UTF-8-encoded PIN.
The file must be memory-mapped to be read. Call ``fstat()`` to determine
the length of the data.

Maximum pin length is 63 bytes.

There are currently no supported keys in the ``options`` vardict.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

pin_fd
  The PIN entered by the user.

options
  Vardict with optional further information.


Signal available since: 1.


.. _org.freedesktop.impl.portal.experimental.Credential::CredentialSelected:

org.freedesktop.impl.portal.experimental.Credential::CredentialSelected
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CredentialSelected (
      session_handle o,
      id s,
      options a{sv}
    )



After receiving a
:ref:`org.freedesktop.impl.portal.experimental.Credential.NotifySelectingCredential`
signal, the backend must prompt the user to select a credential from
the list of credential metadata. The backend must send the ``id`` of
selected credential metadata to the authenticator to
release the credential.

.. note::

   ``id`` is NOT the WebAuthn credential ID; it is an opaque
   identifier used just for selecting the credential in this ceremony.

There are currently no supported keys in the ``options`` vardict.



session_handle
  The :ref:`org.freedesktop.impl.portal.Session` for this authentication ceremony.

id
  The opaque ID representing the selected credential metadata.

options
  Vardict with optional further information.


Signal available since: 1.

