Policy Kit Model - Authentication Agent
Desktop Apps Training - Policy Kit
To gain authorizations through authentication, an Authentication Agent is used. The section defines an abstract interface that applications can use to interact with such an agent. This allows different desktop environments to implement different agents with native look and feel.

The interface is quite simple. Basically, a PolicyKit Authentication Agent must provide the D-Bus session service with the unique name org.freedesktop.PolicyKit.AuthenticationAgent that exposes a single object with the path / that exports the org.freedesktop.PolicyKit.AuthenticationAgent D-Bus interface. The interface is defined by the following D-Bus introspection data: 

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" 
         "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">

<!-- This file is provided by the PolicyKit project -->

<node>
  <interface name="org.freedesktop.PolicyKit.AuthenticationAgent">

    <method name="ObtainAuthorization">
      <!-- IN: PolicyKit action identifier; see PolKitAction -->
      <arg name="action_id" direction="in" type="s"/>

      <!-- IN: X11 window ID for the top-level X11 window the dialog will be transient for (pass zero if no window) -->
      <arg name="xid" direction="in" type="u"/>

      <!-- IN: Process ID to grant authorization to -->
      <arg name="pid" direction="in" type="u"/>

      <!-- OUT: whether the user gained the authorization -->
      <arg name="gained_authorization" direction="out" type="b"/>
    </method>

  </interface>
</node>

This file is available as /usr/share/dbus-1/interfaces/org.freedesktop.PolicyKit.AuthenticationAgent.xml on a system with PolicyKit development packages installed. It can be used to generating client glue code.