         return PersistentToken(token: token, identifier: persistentRef)
     }
 
+    /// Updates the given persistent token with a new token value.
+    ///
+    /// - parameter persistentToken: The persistent token to update.
+    /// - parameter token: The new token value.
+    ///
+    /// - returns: The updated persistent token, or `nil` if an error has occured.
     public func updatePersistentToken(persistentToken: PersistentToken,
         withToken token: Token) -> PersistentToken?
     {

        return keychainItems.flatMap({ PersistentToken(keychainDictionary: $0) })
    }

    public func addToken(token: Token) -> PersistentToken? {
        guard let attributes = token.keychainAttributes,
            persistentRef = addKeychainItemWithAttributes(attributes) else {


import Foundation

/// The `Keychain`'s shared instance is a singleton which represents the iOS system keychain used
/// to securely store tokens.
public final class Keychain {
    /// The singleton `Keychain` instance.
    public static let sharedInstance = Keychain()

    // MARK: Read

    /// Finds the persistent token with the given identifer, if one exists.
    ///
    /// - parameter token: The persistent identifier for the desired token.
    ///
    /// - returns: The persistent token, or `nil` if no token matched the given identifier.
    public func persistentTokenWithIdentifier(identifier: NSData) -> PersistentToken? {
        guard let result = keychainItemForPersistentRef(identifier) else {
            return nil
