Part I API Documentation #

The Secret Service API allows client applications to store secrets securely in a service running in the user's login session.

A secret is something an application wishes to store securely. A good example is a password that an application needs to save and use at a later date.

Each secret is stored together with lookup attributes and a label. These together form an item.

Collections may be accessed via well known aliases. For example an alias called default tells applications which is the default collection to store secrets.

Attributes can and should be stored with a secret to facilitate lookup of the secret at a later date.

A session is established between a client application and a service. A session is used to transfer secrets between the client application and the service.

To access or store secrets, use the GetSecret(), SetSecret() methods on the item interface, or the GetSecrets(), method on the service interface.

Some items and/or collections may be marked as locked by the service. The secrets of locked items cannot be accessed. Additionally, locked items or collections cannot be modified by the client application.

In order to complete various operations, such as unlocking a collection, the service may need to prompt the user for additional information, such as a master password.

A service may implement additional DBus interfaces for further capabilities not included in this specification. Password management applications or other narrowly focused tools should make use of these when necessary.

[TODO: complete]