# Accessing the Keychain

The Keychain is a Mac feature used for storing account passwords for applications. By taking advantage of the keychain, your users do not have to type their password if their keychain is unlocked on their system.

Use the Keychain class to access Mac Keychains for your applications. The classes are: `Keychain</api/macos/keychain>`, `KeychainItem</api/macos/keychainitem>` and `KeychainException</api/exceptions/keychainexception>`.

You should always ask for permission from the user before storing anything in a keychain. You use the System module to get a reference to the default Keychain. You use the KeychainItem class to create, update or find items in the Keychain. If you have more than one Keychain, then you can use the KeyChain constructor to access specific key chains by number.

This code stores a password in the default Keychain:

``` xojo
Var newItem As KeychainItem
If System.KeychainCount > 0 Then
  newItem = New KeychainItem
  ' Indicate the name of the application
  newItem.ServiceName = "MyApplication"
  ' Assign a password to the item
  System.Keychain.AddPassword(newItem, "SecretPassword")
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If

Exception e As KeychainException
  MessageBox("Keychain error: " + e.Message)
```

And this code retrieves the password:

``` xojo
Var itemToFind As KeychainItem
Var password As String
itemToFind = New KeychainItem
' Name to find
ItemToFind.ServiceName = "MyApplication"
' Get the password
password = System.Keychain.FindPassword(itemToFind)
MessageBox("Password: " + password)

Exception e As KeychainException
  MessageBox("Keychain error: " + e.Message)
```

## iCloud Keychain

You can also work with passwords stored in the user's iCloud <span class="title-ref">Keychain</span> by passing `True</api/language/true>` for the optional *Synced* parameter on `Keychain.AddPassword<keychain.addpassword>`, `Keychain.FindPassword<keychain.findpassword>`, `KeychainItem.Remove<keychainitem.remove>`, and `KeychainItem.UpdatePassword<keychainitem.updatepassword>`.

This code stores a password in the iCloud \`Keychain\`:

``` xojo
Var newItem As KeychainItem
newItem = New KeychainItem
newItem.ServiceName = "MyApplication"

Try
  System.Keychain.AddPassword(newItem, "SecretPassword", True)
Catch e As KeychainException
  MessageBox("Keychain error: " + e.Message)
End Try
```

And this code retrieves it:

``` xojo
Var itemToFind As KeychainItem
Var password As String
itemToFind = New KeychainItem
itemToFind.ServiceName = "MyApplication"

Try
  password = System.Keychain.FindPassword(itemToFind, True)
  MessageBox("Password: " + password)
Catch e As KeychainException
  MessageBox("Keychain error: " + e.Message)
End Try
```

<div class="note">

<div class="title">

Note

</div>

When working with iCloud-synced passwords, the `KeychainItem</api/macos/keychainitem>` will not contain a valid `Handle<keychainitem.handle>` after a successful call due to the nature of OS-backed SecureItems.

</div>

**Requirements**

Working with iCloud-synced passwords requires that your macOS app be signed with a Provisioning Profile and Entitlements file that include the `keychain-access-groups` key. The value must use your Team ID (for example, `BW7PU32485`), and that Team ID must match both the Provisioning Profile and the developer certificate used to sign the app.

Entitlements:

``` xml
<key>keychain-access-groups</key>
<array>
    <string>TeamID.*</string>
</array>
```

The Provisioning Profile must also include an entry for `keychain-access-groups` whose value matches the same Team ID.

<div id="/topics/macos/accessing_the_keychain/see_also">

<div class="seealso">

`Keychain</api/macos/keychain>`, `KeychainItem</api/macos/keychainitem>` `KeychainException</api/exceptions/keychainexception>` classes

</div>

</div>