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

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

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

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

Portal to request web credentials.

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

**Version**: Experimental 🧪

The Credential portal allows applications to request web
credentials. The user will be prompted to select a credential,
which the application can use to authenticate. The design of this portal
is highly inspired by the `W3C Credential Management API`_ and the related
credential type specifications.

Currently the only supported credential type is WebAuthn
credentials.

Credentials are created by
`org.freedesktop.portal.experimental.Credential.CreateCredential`_
and retrieved by
`org.freedesktop.portal.experimental.Credential.GetCredential`_.

The D-Bus interface for the Credential portal is available
under the bus name ``org.freedesktop.portal.Desktop`` and the
object path ``/org/freedesktop/portal/desktop``.

.. seealso::
   * `W3C Credential Management API`_
   * `WebAuthn Specification`_

.. _WebAuthn Specification: https://www.w3.org/TR/webauthn-3
.. _W3C Credential Management API: https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API



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

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

.. _org.freedesktop.portal.experimental.Credential:ConditionalCreate:

org.freedesktop.portal.experimental.Credential:ConditionalCreate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ConditionalCreate readable b


Whether conditional mediation is supported for credential registration.

.. seealso::
   `WebAuthn conditionalCreate capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-conditionalcreate>`__




.. _org.freedesktop.portal.experimental.Credential:ConditionalGet:

org.freedesktop.portal.experimental.Credential:ConditionalGet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ConditionalGet readable b


Whether conditional mediation is supported for authentication.

.. seealso::
  `WebAuthn conditionalGet capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-conditionalget>`__




.. _org.freedesktop.portal.experimental.Credential:HybridTransport:

org.freedesktop.portal.experimental.Credential:HybridTransport
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    HybridTransport readable b


Whether hybrid authenticators are supported.

.. seealso::
   `WebAuthn hybridTransport capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-hybridtransport>`__




.. _org.freedesktop.portal.experimental.Credential:PasskeyPlatformAuthenticator:

org.freedesktop.portal.experimental.Credential:PasskeyPlatformAuthenticator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    PasskeyPlatformAuthenticator readable b


Whether a passkey platform authenticator (local or via hybrid transport) is accessible via this API.

.. seealso::
   `WebAuthn passkeyPlatformAuthenticator capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-passkeyplatformauthenticator>`__




.. _org.freedesktop.portal.experimental.Credential:UserVerifyingPlatformAuthenticator:

org.freedesktop.portal.experimental.Credential:UserVerifyingPlatformAuthenticator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    UserVerifyingPlatformAuthenticator readable b


Whether a user-verifying platform authenticator is available via this API.

.. seealso::
   `WebAuthn userVerifyingPlatformAuthenticator capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-userverifyingplatformauthenticator>`__




.. _org.freedesktop.portal.experimental.Credential:RelatedOrigins:

org.freedesktop.portal.experimental.Credential:RelatedOrigins
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    RelatedOrigins readable b


Whether matching origins using WebAuthn Related Origin Requests is supported.

.. seealso::
   `WebAuthn relatedOrigins capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-relatedorigins>`__




.. _org.freedesktop.portal.experimental.Credential:SignalAllAcceptedCredentials:

org.freedesktop.portal.experimental.Credential:SignalAllAcceptedCredentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SignalAllAcceptedCredentials readable b


Whether WebAuthn signalAllAcceptedCredentials() is supported.

.. seealso::
   `WebAuthn signalAllAcceptedCredentials capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-signalallacceptedcredentials>`__




.. _org.freedesktop.portal.experimental.Credential:SignalCurrentUserDetails:

org.freedesktop.portal.experimental.Credential:SignalCurrentUserDetails
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SignalCurrentUserDetails readable b


Whether WebAuthn signalCurrentUserDetails() is supported.

.. seealso::
   `WebAuthn signalCurrentUserDetails capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-signalcurrentuserdetails>`__




.. _org.freedesktop.portal.experimental.Credential:SignalUnknownCredential:

org.freedesktop.portal.experimental.Credential:SignalUnknownCredential
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SignalUnknownCredential readable b


The WebAuthn Client supports signalUnknownCredential().

.. seealso::
   `WebAuthn signalUnknownCredential capability documentation <https://www.w3.org/TR/webauthn-3/#dom-clientcapability-signalunknowncredential>`__




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

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

::

    version readable u




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

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

.. _org.freedesktop.portal.experimental.Credential.CreateCredential:

org.freedesktop.portal.experimental.Credential.CreateCredential
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CreateCredential (
      IN parent_window s,
      IN origin s,
      IN type s,
      IN options a{sv},
      OUT handle o
    )



Requests a new credential to be stored.

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

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

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

* ``handle_token`` (``s``)

  A string that will be used as the last element of the ``handle``. Must be a valid
  object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
  more information about the ``handle``.

* ``public_key`` (``s``):

  A string of JSON that corresponds to the WebAuthn
  `PublicKeyCredentialCreationOptions <https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions>`__
  type.
  Required if ``type`` is ``publicKey``.

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

  The top-level origin of the client window for cross-origin requests.
  Optional. Omit to denote a same-origin request.

The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:

* ``type`` (``s``)

  Type of the created credential.
  Currently, ``publicKey`` is the only supported type.

* ``registration_response_json`` (``s``)

  If ``type`` is ``publicKey``, a string of JSON that corresonds to the WebAuthn
  `PublicKeyCredential <https://www.w3.org/TR/webauthn-3/#publickeycredential>`__
  type with the ``response`` field set as an
  `AuthenticatorAttestationResponse <https://www.w3.org/TR/webauthn-3/#authenticatorattestationresponse>`__.



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

origin
  The origin of the request. Must be a valid HTTPS origin.

type
  Type of the created credential. Currently, ``publicKey`` is the only supported type.

options
  The credential request context and parameters.

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call



.. _org.freedesktop.portal.experimental.Credential.GetCredential:

org.freedesktop.portal.experimental.Credential.GetCredential
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    GetCredential (
      IN parent_window s,
      IN origin s,
      IN options a{sv},
      OUT handle o
    )



Returns a credential.

.. note::

   Parameters for at least one credential request type must be included
   in ``options``. In future versions, multiple credential types may be
   requested in one call to GetCredential(), though there is currently
   only one supported type: ``public_key``. The ``type`` key of the
   response denotes which type of credential was selected by the user
   and returned.

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

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

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

* ``handle_token`` (``s``)

  A string that will be used as the last element of the ``handle``. Must be a valid
  object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
  more information about the ``handle``.

* ``public_key`` (``a{sv}``)

  A dictionary that contains a field ``request_json``, which
  is a string of JSON that corresponds to the WebAuthn
  `PublicKeyCredentialRequestOptions <https://www.w3.org/TR/webauthn-3/#dictionary-assertion-options>`__
  type.

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

  The top-level origin of the client window for cross-origin requests.
  Pass an empty string to denote a same-origin request.

The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:

* ``type`` (``s``)

  Type of the returned credential.
  Currently, ``publicKey`` is the only supported type.

* ``authentication_response_json`` (``s``)

  If ``type`` is ``publicKey``, a string of JSON that corresonds to the
  WebAuthn `PublicKeyCredential <https://www.w3.org/TR/webauthn-3/#publickeycredential>`__
  type with the ``response`` field set as
  an `AuthenticatorAssertionResponse <https://www.w3.org/TR/webauthn-3/#authenticatorassertionresponse>`__.



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

origin
  The origin of the request. Must be a valid HTTPS origin.

options
  The credential request context and parameters.

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call


