SimpleKeychain: a small Keychain wrapper for Apple platforms

Seven methods over the Security framework

SimpleKeychain is described as a simple Keychain wrapper for iOS, macOS, tvOS and watchOS, and the primary language is Swift. The API surface is deliberately small, and reading the usage section top to bottom takes a minute.

You create an instance with no arguments, and it uses your app's bundle identifier as the service name by default:

let simpleKeychain = SimpleKeychain()

If you want a different service name you pass one in, and the documentation gives Auth0 as the example:

let simpleKeychain = SimpleKeychain(service: "Auth0")

Then the operations. Setting a string or data item, checking whether an item is stored, retrieving a string, retrieving data, listing the keys of all stored items, deleting one item, and deleting everything:

try simpleKeychain.set(accessToken, forKey: "auth0-access-token")

let isStored = try simpleKeychain.hasItem(forKey: "auth0-access-token")

let accessToken = try simpleKeychain.string(forKey: "auth0-access-token")

let accessToken = try simpleKeychain.data(forKey: "auth0-credentials")

let keys = try simpleKeychain.keys()

try simpleKeychain.deleteItem(forKey: "auth0-access-token")

try simpleKeychain.deleteAll()

The method names are ordinary and the whole thing reads like a small dictionary type. There is no configuration object, no policy object and no chain of responsibility to assemble.

Every method throws, and the error type is a single enum

The error handling contract is stated in one line: all methods will throw a SimpleKeychainError upon failure. That is the point of the wrapper, because the underlying Security framework calls have the throwing shape and the raw status codes that are awkward to read.

The catch pattern the documentation shows is:

catch let error as SimpleKeychainError {
    print(error)
}

The fact that there is one named error type rather than a set of OSStatus values is the value proposition. A caller can switch on the error and know what happened, rather than comparing against errSecItemNotFound and friends.

Note the consequence for a caller's own code: because every method throws, the call sites need do and try or a throwing context, and reading an optional token is not an optional-returning operation. That is arguably the right design for a Keychain wrapper, since a failed read is a real failure rather than a nil, but it does mean the library does not fit into code that expects optionals.

The generated API documentation is published and is worth pointing at for the full picture, because it is auto-generated from the code comments. There are separate pages for the SimpleKeychain type, for an Accessibility page, and for SimpleKeychainError, and the documentation site is at auth0.github.io/SimpleKeychain. A separate EXAMPLES.md file covers the more advanced features, and V1_MIGRATION_GUIDE.md exists for anyone coming from the 0.x line.

Three installation routes, and the version pin is a tilde

The package ships through Swift Package Manager, CocoaPods and Carthage, and the documentation gives one step for each.

For Swift Package Manager you use the Xcode menu, File > Add Packages..., and paste the repository URL into the Search or Enter Package URL box:

https://github.com/auth0/SimpleKeychain

Then you select the dependency rule and press Add Package.

For CocoaPods, the Podfile gets a line and you run pod install:

pod 'SimpleKeychain', '~> 1.0'

For Carthage, the Cartfile gets a line and you run carthage bootstrap with the xcframeworks flag:

github "auth0/SimpleKeychain" ~> 1.0

One detail to notice: both the Podfile and the Cartfile examples use a pessimistic operator against 1.0, not against the current release. The release list shows 1.3.0 from 2025-03-31 and 1.2.0 from 2024-09-17, with a 1.2.0-beta.0 in between, so the tilde in the example allows 1.x and would resolve to the newest 1.x, but the version you actually get depends on your resolver and on whether a lockfile pins it. If you need a specific patch, say so in your manifest rather than relying on the example.

The repository layout shows a full Swift package: Package.swift at the root, a SimpleKeychain.podspec, an Xcode project, the SimpleKeychain/ source directory, SimpleKeychainTests/ and separate test host targets for tvOS and visionOS, plus a Gemfile for the fastlane release tooling, a .swiftlint.yml, a .semgrepignore and a .shiprc file.

The support policy lets minor releases drop toolchain versions

The support policy is the most interesting document in the repository for anyone depending on the library, and the getting started section flags it as important: check the support policy to learn when dropping Xcode, Swift and platform versions will not be considered a breaking change.

The Xcode rule is that the only supported versions are those that can currently be used to submit apps to the App Store. Once a version becomes unsupported, dropping it is not a breaking change and is done in a minor release.

The Swift rule is similar in shape. The minimum supported Swift minor version is the one released with the oldest supported Xcode version, and once a Swift minor becomes unsupported it is dropped in a minor release.

For platforms, only the last four major versions are supported, including the current one, and dropping one is a minor release. The example given is iOS 16, which will cease to be supported once it is no longer among the four most recent major iOS releases. On macOS the yearly named releases count as a major platform version regardless of the actual version numbers, so Sonoma and Sequoia are major versions in this policy's terms.

This is a coherent and unusual position. Most libraries treat a toolchain bump as a major version because their consumers pin. This one reserves major versions for API changes and uses minor releases to track the platform, which means your build can move under you without a major version bump. The stated requirement today is iOS 16.0 or later, macOS 13.0 or later, tvOS 16.0 or later, watchOS 9.0 or later, with Xcode 26.x and Swift 6.0.

Where the wrapper stops and the Keychain begins

The limit is scope, and it is the sort of limit you only notice when you need the missing piece.

There is no access group support in the documented API. The Apple Keychain has an access group concept that lets an app and its extensions share stored items, and the mechanism for it is a group identifier on the query. The usage section here covers a service name and nothing else, and the service name is what scopes the items for the app. An app with a share extension that needs the same token in both processes has to reach past this wrapper.

There is no synchronisation and no user-presence gating in the documented surface either. The Keychain supports iCloud Keychain synchronisation and the biometry or device-passcode requirement on retrieval, and neither appears in the API as described. A product that needs the user to authenticate before a token is released, or that needs a token on two of the user's devices, is outside what this wrapper offers.

The accessibility page in the generated documentation is worth a look, because it is the one place where the wrapper appears to handle something the raw framework does not surface cleanly, and the fact that it has its own page is a hint about what the wrapper adds.

The third limit is the obvious one: this is Apple platforms only. The Keychain is an Apple system facility, so there is no cross-platform story here, and a team with a shared secret store across iOS, Android and the web needs something else.

Maintenance, security reporting and who owns it

The repository is not archived, and the last push was on 2026-10-15. The most recent release is 1.3.0 from 2025-03-31, before 1.2.0 from 2024-09-17 and the 1.2.0-beta.0 from 2024-07-02,

The project is Auth0's, and that is visible in more than the name. The documentation links to Auth0's own documentation site, the readme ends with the Auth0 logo and the line about Auth0 being an easy-to-implement authentication and authorization platform, and the feedback section points at Auth0's general contribution guidelines and code of conduct from their open source template, alongside this project's own contribution guide.

The security reporting instruction is specific and worth reading: do not report security vulnerabilities on the public GitHub issue tracker, since the Responsible Disclosure Program details the procedure for disclosing security issues. Given that the library exists to hold credentials, that is not boilerplate.

The licence is MIT, stated in the readme with a link to the LICENSE file. For a dependency that stores tokens, that is the simple case, and there is no additional terms in the repository to read beyond the standard grant.

There is also a set of release and CI tooling worth noting for anyone tracking it: fastlane/ for releases, opslevel.yml, codecov.yml for coverage, a CHANGELOG.md, and a.github/ directory carrying the build workflow.

Editorial conclusion

SimpleKeychain is the right choice for an Apple platform app that has a handful of secrets to store and wants a typed, throwing Swift API over the Keychain without hand-writing Security framework calls, because the whole surface is seven methods and the service name defaulting to the bundle identifier removes the most common source of Keychain mistakes. It is the wrong choice for an app that needs shared keychain access between a main app and an extension, because the documented API does not expose an access group, and it is the wrong choice if you need synchronisation or user-presence gating. Before you adopt it, check the three things the project puts in front of you: the platform floor, which is iOS 16, macOS 13, tvOS 16 and watchOS 9 with Xcode 26.x and Swift 6.0; the support policy, which lets the maintainers drop toolchain and platform versions in a minor release rather than a major one, so your build can change under you; and the installation route, since the Podfile and Cartfile examples pin the 1.0 line with a tilde while the current release is 1.3.0, so a strict resolver may resolve differently from what you expect.

Frequently asked questions

Official sources

1. auth0/SimpleKeychain on GitHub
2. License: MIT
3. Project website
4. README
5. Releases