Skip to main content
Chappie stores OAuth credentials in the iOS or macOS Keychain automatically after sign-in and restores them on the next launch — your app never needs to manage token storage manually. You control where and how those credentials live through the Keychain-related fields in ChappieConfiguration.

​
Default settings

FieldDefault value
keychainService"com.chappie.sdk"
keychainAccount"default"
keychainAccessGroupnil
keychainAccessibility.whenUnlockedThisDeviceOnly
Out of the box, credentials are stored under a single generic-password Keychain item with the most restrictive accessibility level: readable only while the device is unlocked, never migrated to another device, and excluded from iCloud Keychain sync and device backups.

​
Keychain accessibility options

ChappieKeychainAccessibility maps directly to Security framework kSecAttrAccessible constants:
​
whenUnlockedThisDeviceOnly
ChappieKeychainAccessibility
Default and recommended. The Keychain item is readable only while the device is unlocked. It never leaves the device — not through iCloud Keychain, backups, or migration. Use this for all foreground-only apps.
​
afterFirstUnlockThisDeviceOnly
ChappieKeychainAccessibility
The Keychain item is readable after the user unlocks the device at least once after a reboot. Background processes (VoIP, background fetch, push-triggered extensions) can read credentials without requiring the screen to be unlocked. This setting still prevents the item from leaving the device.
Enable .afterFirstUnlockThisDeviceOnly only when your app genuinely needs to read credentials from a background extension or background task. This accessibility level makes the credential readable by any process running in the background under your app’s entitlements. Keep the default .whenUnlockedThisDeviceOnly for all foreground-only apps.

​
Setting a custom Keychain service

Override the default service identifier to namespace your credentials separately from the SDK default: 
let config = ChappieConfiguration(
    keychainService: "com.myapp.chappie",
    keychainAccount: "default"
)

let authSession = Chappie.authSession(configuration: config)
let client = Chappie.client(configuration: config)
Using your own reverse-DNS service name avoids any accidental overlap with other apps that use the SDK at its defaults.

​
Shared Keychain with app groups or extensions

To share credentials between your main app and an extension (Share Extension, Widget, Notification Service Extension), set keychainAccessGroup to your app group’s shared Keychain identifier. Your app target must have the Keychain Sharing entitlement and list that access group: 
let config = ChappieConfiguration(
    keychainAccount: currentUser.id,
    keychainAccessGroup: "TEAMID.com.example.shared"
)

let authSession = Chappie.authSession(configuration: config)
let client = Chappie.client(configuration: config)
Replace TEAMID with your ten-character Apple Developer Team ID and com.example.shared with the group identifier configured in your entitlement file.

​
Multi-account apps

For apps that support multiple signed-in accounts simultaneously, use a distinct keychainAccount value per user. Each value creates a separate Keychain item under the same service, so accounts do not interfere with one another: 
// User A
let configA = ChappieConfiguration(keychainAccount: userA.id)
let sessionA = Chappie.authSession(configuration: configA)
let clientA  = Chappie.client(configuration: configA)

// User B
let configB = ChappieConfiguration(keychainAccount: userB.id)
let sessionB = Chappie.authSession(configuration: configB)
let clientB  = Chappie.client(configuration: configB)
Use a stable, non-PII identifier like a UUID or opaque server-assigned user ID for the account slot name.
Raw access tokens, refresh tokens, and OAuth internals are never surfaced through Chappie’s public API. ChappieAuthSession exposes an auth state enum and ChappieAccountInfo (email, user ID, account ID, plan) — never the underlying bearer token. This prevents accidental token logging or transmission through app code.