Sharing

The owner of a record shares it by creating an invite. The recipient previews the invite, accepts it with the invite's secret and, when the invite asks for one, a passcode. From then on the record appears in the recipient's vault with permission View. The owner can list and revoke invites and take access away again.

Sharing runs through the same store as the rest of the vault: dispatch VaultAction.Share with a SharingRequest on VaultStore and read the result from the sharing field of its state. Sharing needs a signed-in session: in a transient session every sharing request fails with TransientNotSupported.

How an invite travelsCopy Anchor Link

1. The owner dispatches CreateInvite for one of their records. The result, sharing.created, holds the invite and its secret.
2. Your app delivers the invite's linkId and the secret to the recipient, and the passcode, if the invite has one, through a separate channel. The SDK does not build or send the message.
3. The recipient dispatches PreviewInvite with the linkId. The result, sharing.preview, shows the invite, including its id, status and whether it asks for a passcode.
4. The recipient dispatches AcceptInvite with the invite id, the secret and the passcode. The SDK unwraps the record key with the secret, stores the record in the recipient's vault and sets sharing.acceptedRecordId.

Only the holder of the secret can open the record: the invite carries the record key sealed under a key derived from the secret, and the secret itself never reaches Folio in the clear.

RequestsCopy Anchor Link

On iOS the requests are lowerCamelCase cases with labeled fields, such as .acceptInvite(inviteId:secret:passcode:); on Android they are classes of SharingRequest, such as SharingRequest.AcceptInvite(inviteId, secret, passcode), and SharingRequest.LoadInvites is an object; on the web they are functions of SharingRequest, such as SharingRequest.acceptInvite(inviteId, secret, passcode), and SharingRequest.loadInvites is a value. Wrap each request in VaultAction.Share before you dispatch it.

LoadInvites and LoadAccess return up to 100 entries each. A failed request leaves sharing as it was and sets error in the vault state; a successful one clears error. busy is true while a request runs.

let invite = InviteRequest(audience: .open(multiUse: false), expiresAt: nil, passcode: "4821")
try vault.dispatch(action: .share(value: .createInvite(recordId: record.header.id, invite: invite)))

try vault.dispatch(action: .share(value: .previewInvite(linkId: linkId)))
try vault.dispatch(
    action: .share(value: .acceptInvite(inviteId: preview.id, secret: secret, passcode: "4821"))
)

InviteRequestCopy Anchor Link

InviteAudienceCopy Anchor Link

On iOS the cases are .open(multiUse:) and .account(accountId:), on Android InviteAudience.Open(multiUse) and InviteAudience.Account(accountId), and on the web InviteAudience.open(multiUse) and InviteAudience.account(accountId), which build { type: 'OPEN', value: { multiUse } } and { type: 'ACCOUNT', value: { accountId } }.

An account id is the userId of the account's session identity. FolioSDK has no directory that finds an account by email address or name: the recipient reads their own userId from SessionStore and gives it to the inviter through your app or your backend. The account ids the SDK already shows you are the recipients in AccessGrant and the owner of a shared record in header.ownerId.

expiresAt is an Int64 on iOS, a Long on Android and a bigint on the web. It counts seconds, not milliseconds: an invite that expires in a day is BigInt(Math.floor(Date.now() / 1000) + 86_400) on the web. The recipient sends the passcode with AcceptInvite, and Folio checks it against the hash.

SharingViewCopy Anchor Link

The sharing field of the vault state.

created keeps the last created invite until the next CreateInvite replaces it. Keep the secret only as long as you need it to deliver the invite.

CreatedInviteLinkCopy Anchor Link

InviteSummaryCopy Anchor Link

expiresAt keeps the seconds of the InviteRequest, while createdAt and updatedAt are in milliseconds. Multiply expiresAt by 1000 before you compare it with the other two.

InviteStatusCopy Anchor Link

InviteStatus and InviteChallengeType have no payloads. On iOS the cases are .pending, .consumed, .rejected, .revoked and .passcode; on Android InviteStatus.PENDING, InviteStatus.CONSUMED, InviteStatus.REJECTED, InviteStatus.REVOKED and InviteChallengeType.PASSCODE; on the web the strings 'PENDING', 'CONSUMED', 'REJECTED', 'REVOKED' and 'PASSCODE', also available as InviteStatus.PENDING and so on.

let canAccept = preview.status == .pending
let needsPasscode = preview.challenges.contains(.passcode)

AccessGrantCopy Anchor Link

Shared records in the recipient's vaultCopy Anchor Link

An accepted record appears in the recipient's records like any other record, with the owner's account in header.ownerId and header.permission set to View. The recipient can read it and write its own settings for it, but cannot update, delete or restore it. A conflict of RemoteRevoked means the account lost access to the record; see Conflicts.

Issued documentsCopy Anchor Link

An organization delivers a document it issues to the person as an Account invite. The SDK accepts these invites on its own, once Folio confirms that an invite carries an issued document, and the document appears in FolioDocumentListStore. Your app does not dispatch AcceptInvite for them. See Automatic reception.

The SDK never accepts any other invite on its own. An invite another account sends stays in incoming until your app accepts or rejects it.

ErrorsCopy Anchor Link

Sharing requests fail with an error in error of the vault state, a VaultErrorView whose details is the VaultError. The cases specific to sharing:

See Vault errors for the full list and the spelling of the cases on each platform, and Types on each platform for i64, Bool and the list types in the tables above.