A class for performing actions on a credential stored in the Secure Element.
Create a credential session with the ``startSession()`` method. After you start a session, the session has three states:
- term Management: In this default state, you can list, add, and delete credentials in the Secure Element.
- term Wired: The wired state allows you to exchange data with a credential-corresponding entity (an _applet_) in the Secure Element.
- term Card Emulation: In the card emulation state, your credential can communicate with a contactless card reader.
The framework provides SwiftUI and UIKit user interfaces for your app to display while using the wired and card emulation states.
You can read the current state at any time from the ``state`` property. The ``eventStream`` property provides an <doc://com.apple.documentation/documentation/Swift/AsyncStream> of events from both your own actions on credentials and outside sources like detecting an NFC reader's RF field.
An app can have only one active session at a time. When your app no longer needs the credential session, call ``invalidate()``. If your app goes into the background, the system automatically invalidates your session after a short delay. In wired mode, the system invalidates the session if it goes 15 seconds without performing a ``transceive(_:)`` call.
### Use a session in an app extension
Certain methods in ``CredentialSession`` are only appropriate for use in apps.
If you're writing an app extension, such as for an identity service provider, use only the following methods:
* ``startSession()``
* ``listCredentials()``
* ``performWiredTransaction(using:over:instanceAID:)``
* ``transceive(_:)``
* ``endWiredMode()``
* ``invalidate()``
Requests a session to view, manage, or use credentials in the Secure Element.
To start a session from an app, the app needs to be in the foreground.
Apps and app extensions that create credential sessions must have the <doc://com.apple.documentation/bundleresources/entitlements/com.apple.developer.secure-element-credential> entitlement. If your app or app extension lacks this entitlement, calls to ``SecureElementCredential`` APIs raise <doc://com.apple.documentation/documentation/Swift/fatalError(_:file:line:)>.
If you want to make your app or app extension eligible to be the system's default contactless app, you need the <doc://com.apple.documentation/documentation/bundleresources/entitlements/com.apple.developer.secure-element-credential.default-contactless-app> entitlement as well.
> Note: If your app extension is an identity credential provider, use <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.identity-document-services.document-provider.mobile-document-types> to include your mobile document provider app extension in the picker when someone using the device receives a web request to present their provisioned identity credential. See <doc://com.apple.documentation/documentation/identitydocumentservices/implenting-as-an-identity-document-provider> for more information about using this entitlement.
This method is asynchronous, which requires that you call it with the `await` keyword. When the system is ready to provide the session resource, the following events occur:
* The person using the app receives a GDPR privacy information sheet.
* The first time the app tries to access a credential session, the person using the app receives an alert to allow usage of the Secure Element. If they accept, the session proceeds normally. If they decline, the session invalidates and new sessions for this app fail immediately. To create a valid session, the person using the app needs to allow Secure Element access for the app in Settings.
Sessions start in the ``CredentialSession/State-swift.enum/management`` state. An app can have only one active session at a time. When your app no longer needs the credential session, call ``invalidate()``. If your app goes into the background, the system automatically invalidates your session after a short delay.
- The most common errors are:
- ``ErrorCode/resourceUnavailable``: The system service is temporarily unavailable.
- ``ErrorCode/accessDenied``: The user declined to grant access to the Secure Element.
- ``ErrorCode/ineligible``: The device or user configuration doesn't support this service.
- ``ErrorCode/conditionsNotSatisfied``: The iCloud account or passcode conditions aren't met.
Deletes a credential on the Secure Element.
- Parameters:
- credential: The credential to delete.
- The most common errors are:
- ``ErrorCode/invalidSessionState``: The session isn't in the ``CredentialSession/State-swift.enum/management`` state.
get · iOS 18.4+
secureElementInfo
TypeScript
get secureElementInfo(): Promise<CredentialSession_SecureElementInfo>
Swift declaration
var secureElementInfo: CredentialSession.SecureElementInfo { get async throws }
A property that provides information about the Secure Element hardware.
You can use the certificate in the ``CredentialSession/SecureElementInfo-struct`` to authenticate against the Certification Authority of the Secure Element hardware.
- The most common errors are:
- ``ErrorCode/featureUnavailable``: The Secure Element credential feature isn't available on this platform.
- ``ErrorCode/sessionInvalidated``: The credential session has been invalidated.
Creates a credential in the Secure Element.
This method installs into the Secure Element an applet bundle that you've submitted through the [Apple Business Register](https://register.apple.com/login) portal.
> Note: If there is not enough space in the Secure Element to provision the new credential, the system shows a space management UI over the current app.
A person using the device can use this interface to remove other credentials to free up space or cancel the provisioning attempt.
- Parameters:
- configurationUUID: A UUID corresponding to an product configuration configured on the [Apple Business Register](https://register.apple.com/login) portal. The system uses the corresponding product configuration to provision the instance associated with the created credential. The UUID is opaque to the device.
- name: A friendly name assigned for ease of identification the provisioned credential. The name is opaque to the device.
- Returns: A ``CredentialSession/Credential``, initialized with the ``CredentialSession/Credential/State/installationPending`` state.
- The most common errors are:
- ``ErrorCode/invalidInput``: The `name` parameter is empty.
- ``ErrorCode/invalidSessionState``: The session isn't in the ``CredentialSession/State-swift.enum/management`` state.
- ``ErrorCode/invalidProductConfigID``: The `configurationUUID` does not correspond to a known product configuration.
- ``ErrorCode/insufficientSpace``: The Secure Element doesn't have enough storage space.
- ``ErrorCode/network``: A network error occurred during provisioning.
- ``ErrorCode/conditionsNotSatisfied``: The iCloud account or passcode conditions aren't met.
method · iOS 18.1+
invalidate
TypeScript
invalidate(): Promise<void>
Swift declaration
func invalidate() async throws
Inmediately invalidates a session.
Call this method when your app no longer needs a credential session. The system automatically invalidates a session when it deallocates, or when it encounters underlying errors.
When a session invalidates, its event stream also invalidates and deallocates.
You can invalidate a session while in any session state.
get · iOS 18.1+
isEligible
TypeScript
static get isEligible(): Promise<boolean>
Swift declaration
static var isEligible: Bool { get async throws }
A Boolean value that indicates whether the app or app extension is eligible to start a credential session.
Always check the value of this property before calling ``startSession()`` to dynamically determine if the current device and user configuration can use the Secure Element credential service.
- The most common errors are:
- ``ErrorCode/resourceUnavailable``: The system service is temporarily unavailable.
func transceive(_ data: Data) async throws -> Data
Send a wired command Application Protocol Data Unit (APDU) to the credential to complete a transaction or a card content management task.
- Parameters:
- data: The APDU as a <doc://com.apple.documentation/documentation/Foundation/Data> instance.
- Returns: A response APDU.
Before calling this method, make sure the credential session state is ``CredentialSession/State-swift.enum/wired(credential:)``. The state transitions to ``CredentialSession/State-swift.enum/management`` if the call encounters a ``CredentialSession/ErrorCode/resourceUnavailable`` error; otherwise the state remains unchanged.
Use this method to perform the web presentment transaction after calling ``performWiredTransaction(using:over:instanceaid:)``.
> Note: When performing a ``transceive(_:)`` call, the system grants your app a 15-second grace period from invalidating the session, in the event your app goes into the background.
- The most common errors are:
- ``ErrorCode/invalidSessionState``: The session isn't in the ``CredentialSession/State-swift.enum/wired(credential:)`` state.
- ``ErrorCode/commandNotSupported``: The APDU represents an unsupported Secure Element command.
- ``ErrorCode/resourceUnavailable``: The system resource is unavailable. The session transitions to ``CredentialSession/State-swift.enum/management``.
- ``ErrorCode/acquiredResourceRelinquished``: The shared system resource was relinquished during the operation.
get · iOS 18.1+
eventStream
TypeScript
get eventStream(): Promise<SDKSequence<CredentialSession_Event>>
Swift declaration
var eventStream: AsyncStream<CredentialSession.Event> { get async }
An asynchronous stream of session events.
Consume and handle events as the session produces then. Do this with a `for-await-in` loop over the stream, like the following example:
```
for await event in session.eventStream {
// Handle event.
}
```
method · iOS 18.1+
endWiredMode
TypeScript
endWiredMode(): Promise<void>
Swift declaration
func endWiredMode() async throws
Ends wired mode and returns to management state.
The credential session state must be ``CredentialSession/State-swift.enum/wired(credential:)`` prior to calling this method.
Enters wired mode to perform maintenance operations with the given credential.
- Parameters:
- credential: The installed credential with which to enter wired mode.
You can call this method in any session state. If successful, the state transitions to ``CredentialSession/State-swift.enum/wired(credential:)``. The state transitions to ``CredentialSession/State-swift.enum/management`` if the call encounters a ``CredentialSession/ErrorCode/resourceUnavailable`` error; otherwise the state remains unchanged.
- The most common errors are:
- ``ErrorCode/invalidCredentialState``: The credential isn't in the ``Credential/State/installed(instances:)`` state.
- ``ErrorCode/resourceUnavailable``: The system resource is unavailable. The session transitions to ``CredentialSession/State-swift.enum/management``.
Retrieves a list of of credentials to which the app has access rights.
When you call this method, the framework caches a snapshot of these credentials. Because credentials can change, refresh your data models whenever your app performs any kind of write operation using the ``SecureElementCredential`` framework. Also update whenever your app returns to the foreground.
> Note: When you call this method from an app extension that has the <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.identity-document-services.document-provider.mobile-document-types> entitlement, the returned array contains only credentials configured as Government ID credentials on the [Apple Business Register](https://register.apple.com/login) (ABR) portal.
- Returns: An array of credentials to which the calling app has access rights. The order of credentials in this array is random.
- The most common errors are:
- ``ErrorCode/sessionInvalidated``: The credential session has been invalidated.
- ``ErrorCode/invalidSessionState``: The session isn't in the ``CredentialSession/State-swift.enum/management`` state.
get · iOS 18.1+
unownedExecutor
TypeScript
get unownedExecutor(): SDKHandle
Swift declaration
nonisolated final var unownedExecutor: UnownedSerialExecutor { get }
Retrieve the executor for this actor as an optimized, unowned
reference.
This property must always evaluate to the same executor for a
given actor instance, and holding on to the actor must keep the
executor alive.
This property will be implicitly accessed when work needs to be
scheduled onto this actor. These accesses may be merged,
eliminated, and rearranged with other work, and they may even
be introduced when not strictly required. Visible side effects
are therefore strongly discouraged within this property.
- SeeAlso: ``SerialExecutor``
- SeeAlso: ``TaskExecutor``
Indicates that the app intends to present a credential to a contactless interface.
Call this method when your app is in the foreground and showing a user interface appropriate for connecting to a contactless reader.
When you acquire this assertion, your app's credential presentment can't be interrupted by other entities' presentment intents. Specifically, this prevents a default NFC app from interrupting when it detects an NFC reader's RF field.
If another entity is already presenting a credential, calling this method throws an error. In this case, try calling the method again later.
Hold on to this instance as long as you need it (up to 60 seconds) to complete your credential presentment activity. When you're done, call ``SecureElementCredential/CredentialSession/PresentmentIntentAssertion/relinquish()`` to end the presentment assertion.
Repetitive acquisition of the assertion mechanism may result in a cooldown before being able to acquire the next assertion.
The exclusive use of the presentment intent expires after a predetermined timeout period. When this happens, the credential session's event stream produces a ``CredentialSession/Event/presentmentIntentAssertionTimeout`` event.
- Returns: A ``CredentialSession/PresentmentIntentAssertion`` object, representing exclusive access to presentment intent for a short time.
- The most common errors are:
- ``ErrorCode/resourceUnavailable``: The system service is unavailable, or another entity is currently presenting a credential.
get · iOS 18.1+
state
TypeScript
get state(): Promise<CredentialSession_State>
Swift declaration
var state: CredentialSession.State { get async }
The current state of the session.
Sessions start in the ``CredentialSession/State-swift.enum/management`` state. Calls to the wired or card emulation APIs change the state to ``CredentialSession/State-swift.enum/wired(credential:)`` or ``CredentialSession/State-swift.enum/cardEmulation(credential:)``. Leaving wired or card emulation mode returns the state to ``CredentialSession/State-swift.enum/management``.
Explicitly invalidating the session, encountering an error, or the app entering the background changes the state to ``CredentialSession/State-swift.enum/invalid``. An invalid session can't return to one of the other states.
init · iOS 18.1+
init
TypeScript
static init(): CredentialSession
Swift declaration
init()
Creates an empty credential session.
Don't use this initializer to create a session. Use ``CredentialSession/startSession()`` to request and start a session.
