iOS integration guide

01Before you start

You need two things from your Datacove tenant administrator before writing any code.

02How it fits together

The user never sets a password. They prove they own a phone number or email address with a six-digit code, and the app receives a token pair it keeps refreshing for as long as the user stays signed in.

03Sign in with OTP

Offer phone, email, or both. They work the same way: request a code, verify it, and activate the account the first time it signs in. Each phone number or email address maps to one account per tenant, created automatically on the first request.

Phone number

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}

struct TokenPair: Codable { let accessToken: String; let refreshToken: String; let expiresIn: Int }

struct DatacoveClient {
    let baseURL: URL          // e.g. https://api.example.com/api
    let apiKey: String        // the IOS tenant API key

    func requestMobileOtp(phone: String, name: String? = nil) async throws {
        _ = try await post("auth/v1/mobile/request-otp",
                           body: ["phoneNumber": phone, "name": name, "channel": "sms"], withKey: true)
    }

    func verifyMobileOtp(phone: String, otp: String) async throws -> TokenPair {
        let data = try await post("auth/v1/mobile/verify-otp",
                                  body: ["phoneNumber": phone, "otp": otp, "channel": "sms"], withKey: true)
        return try JSONDecoder().decode(TokenPair.self, from: data)
    }

    func post(_ path: String, body: [String: String?], withKey: Bool = false, token: String? = nil) async throws -> Data {
        var request = URLRequest(url: baseURL.appendingPathComponent(path))
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        if withKey { request.setValue(apiKey, forHTTPHeaderField: "x-api-key") }
        if let token { request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization") }
        request.httpBody = try JSONSerialization.data(withJSONObject: body.compactMapValues { $0 })
        let (data, response) = try await URLSession.shared.data(for: request)
        guard let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode) else {
            throw APIError.from(data: data, response: response)
        }
        return data
    }
}

Email

Identical to the phone flow, with an email address instead of a number and no channel choice. Requesting a new code within 60 seconds of the last one returns 429.

{ "email": "jane@example.com", "name": "Jane Doe" }

{ "email": "jane@example.com", "otp": "123456" }

Activate and load the profile

A brand-new account comes back from verify with status: "CREATED" in its access token. Call activate once to move it to ACTIVE; it returns a fresh token pair that replaces the one you just stored. The call is idempotent, so if you're unsure whether it succeeded (a timeout, a dropped connection), just call it again.

{
  "name": "Jane Doe",
  "phone": "14165550199",
  "country": "CA",
  "timezone": "America/Toronto",
  "status": "ACTIVE",
  "wallet": { "WALLET": 25, "TRIAL": 0, "SUBSCRIPTION": 0 }
}

To edit the name or timezone, use PATCH /users/v1/profile. App Store rules require in-app account deletion: use DELETE /users/v1/account.

04Keeping the session alive

Access tokens last 30 minutes. Refresh tokens last 7 days and change every time you use one, so a user who opens the app at least once a week stays signed in indefinitely.

{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }

Rules for a well-behaved client

• Store tokens in the Keychain. If an app extension shares the session, put the item in a shared Keychain access group so both read the same, latest tokens.
• Refresh proactively. Refresh about a minute before expiresIn elapses, and also when any request returns 401, then retry that request once.
• Refresh one at a time. Route every refresh through a single actor so concurrent requests share one refresh. Two refreshes that arrive within 30 seconds of each other with the same token both succeed and return the same new token. Anything later with an old token is treated as a stolen token and ends the session.
• Re-read before refreshing. When an app and an extension share tokens, read the Keychain again just before refreshing. Another process may already have rotated the token.

actor SessionManager {
    private let client: DatacoveClient
    private let keychain: TokenKeychain        // shared access group if an extension uses it
    private var inFlight: Task<TokenPair, Error>?

    init(client: DatacoveClient, keychain: TokenKeychain) {
        self.client = client
        self.keychain = keychain
    }

    /// Returns a usable access token, refreshing it at most once at a time.
    func validAccessToken(rejected: String? = nil) async throws -> String {
        if let task = inFlight { return try await task.value.accessToken }
        guard let current = keychain.read() else { throw APIError.signedOut(code: nil) }
        // Another caller (or process) already rotated it: use the newer token.
        if let rejected, current.accessToken != rejected { return current.accessToken }

        let task = Task { () throws -> TokenPair in
            let data = try await client.post("auth/v1/refresh", body: ["refreshToken": current.refreshToken])
            let pair = try JSONDecoder().decode(TokenPair.self, from: data)
            try keychain.write(pair)               // persist before anyone uses it
            return pair
        }
        inFlight = task
        defer { inFlight = nil }
        do {
            return try await task.value.accessToken
        } catch let APIError.http(status, code, _) where status == 401 {
            keychain.clear()
            throw APIError.signedOut(code: code)   // SESSION_EVICTED, TOKEN_REUSED, ...
        }
    }
}

When a refresh is rejected

A 401 from refresh, or from any authenticated request, carries a machine-readable code inside error. Use it to tell the user why they were signed out.

{
  "statusCode": 401,
  "timestamp": "2026-10-02T09:30:00.000Z",
  "path": "/api/auth/v1/refresh",
  "error": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "You were signed out because this account signed in on another device.",
    "code": "SESSION_EVICTED"
  }
}

Devices and signing out

An account can be signed in on up to 5 devices at once. Signing in on a sixth ends the least recently created session. The same endpoints let you build a "signed-in devices" screen:

05Running workflows

A workflow is an AI task with a defined set of inputs. Fetch its definition, render a form from its inputs, then execute it. Each run costs the credits configured for that workflow, deducted from wallet.WALLET.

Discover workflows

GET /workflows/v1/:pageNo/:pageSize returns { data, meta }, filtered to what your tenant offers. Optional query parameters: search, category, featured. Then fetch one by its id, for example GET /workflows/v1/wf-sec-001, to get its inputs.

Build the form from inputs

[
  {
    "key": "url",
    "label": "Website address",
    "type": "text",
    "placeholder": "https://example.com",
    "validation": { "required": true }
  },
  {
    "key": "document",
    "label": "Document",
    "type": "file",
    "fileOptions": { "accept": ".pdf,.docx", "maxSizeMb": 10, "multiple": false }
  }
]

func executeWithFile(workflowId: String, fileKey: String, fileURL: URL, mimeType: String, token: String) async throws -> Data {
    let boundary = "Boundary-\(UUID().uuidString)"
    var request = URLRequest(url: baseURL.appendingPathComponent("workflows/v1/execute"))
    request.httpMethod = "POST"
    request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
    request.setValue(appVersion, forHTTPHeaderField: "X-App-Version")   // CFBundleShortVersionString
    request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

    var body = Data()
    func field(_ name: String, _ value: String) {
        body.append("--\(boundary)\r\nContent-Disposition: form-data; name=\"\(name)\"\r\n\r\n\(value)\r\n")
    }
    field("id", workflowId)                // plain text field
    field("input", "{}")                   // JSON string of the non-file inputs, {} if none
    body.append("--\(boundary)\r\n")
    // Each file part is named after its input key.
    body.append("Content-Disposition: form-data; name=\"\(fileKey)\"; filename=\"\(fileURL.lastPathComponent)\"\r\n")
    body.append("Content-Type: \(mimeType)\r\n\r\n")
    body.append(try Data(contentsOf: fileURL))
    body.append("\r\n--\(boundary)--\r\n")

    let (data, _) = try await URLSession.shared.upload(for: request, from: body)
    return data
}

private extension Data {
    mutating func append(_ string: String) { append(Data(string.utf8)) }
}

Two kinds of response

Each workflow always responds the same way, so a client can simply check for eventId in the response.

06Getting report results

Use the realtime channel to be told the moment a report is ready, and keep polling as a fallback. Both use the eventId from execute.

A user's past runs are listed by GET /workflows/reports/v1/history/:page/:limit. If the app goes to the background during a long run, poll the report when it returns to the foreground.

07App Store purchases

Apps can sell two kinds of product with StoreKit 2. Your tenant administrator creates both in the Datacove catalog, using the same product ids you set up in App Store Connect.

Trial and entitlement

Workflows covered by a plan are available while the user has an active trial or an active plan. Without either, executing one returns 403 with code: "ENTITLEMENT_INACTIVE". The account is what holds the plan, so it follows the user to every device they sign in on. Read the state at launch, when the app returns to the foreground, and after every purchase:

{
  "trial": { "status": "not_started" },
  "trialOffer": { "available": false },
  "entitlement": {
    "status": "active",
    "productId": "650f1c2e9b1d4a0012ab34cd",
    "platform": "apple",
    "currentPeriodEnd": "2026-11-01T08:00:00.000Z"
  },
  "plans": [
    {
      "productId": "650f1c2e9b1d4a0012ab34cd",
      "platformProductId": "com.example.app.yearly",
      "displayName": "1 Year Protection",
      "interval": "annual",
      "gatedWorkflowId": "wf-sec-001"
    }
  ],
  "canExecuteGatedWorkflow": true,
  "serverTime": "2026-10-02T09:30:00.000Z"
}

Purchases

Sign the user in before they buy, so the purchase is tied to their account.

1. Buy with product.purchase() and keep only .verified transactions.
2. Confirm it with the backend straight away: call verify-purchase with the transaction id and product id.
3. Finish the transaction after a 200 with transaction.finish(). Don't finish it before the backend confirms, or a failed call can't be retried.
4. Listen for Transaction.updates from app launch, and on launch also walk Transaction.unfinished. Both catch purchases that completed while the app wasn't running, such as Ask to Buy approvals and renewals. Send each through verify-purchase; verifying the same transaction twice is safe.
5. After sign-in, send each plan in Transaction.currentEntitlements through verify-purchase once, so a plan bought earlier is linked to the account.

{ "kind": "credit_package", "creditsGranted": 500 }

{
  "kind": "service_entitlement",
  "entitlementStatus": "active",
  "currentPeriodEnd": "2026-11-02T09:30:00.000Z"
}

@MainActor
final class PurchaseManager {
    private var updatesTask: Task<Void, Never>?

    /// Call once at app launch.
    func start() {
        updatesTask = Task {
            for await result in Transaction.updates { await self.handle(result) }
        }
        Task {
            for await result in Transaction.unfinished { await self.handle(result) }
        }
    }

    func buy(_ product: Product) async throws {
        if case .success(let result) = try await product.purchase() {
            await handle(result)
        }
    }

    private func handle(_ result: VerificationResult<Transaction>) async {
        guard case .verified(let transaction) = result else { return }   // ignore unverified
        do {
            try await api.verifyPurchase(
                platform: "apple",
                platformProductId: transaction.productID,
                transactionId: String(transaction.id)
            )
            await transaction.finish()            // only after the backend has granted it
            await refreshWalletAndEntitlement()
        } catch {
            // Leave it unfinished: Transaction.unfinished will offer it again on next launch.
        }
    }
}

Moving a plan to another account

An account is a phone number or email; a plan is paid for by an Apple ID. When someone signs in with a new number on a phone whose Apple ID already pays for a plan on their old account, verify-purchase answers 409 PURCHASE_LINKED_TO_ANOTHER_ACCOUNT. Apple won't sell the same subscription again while it's active, so the user can only get it on the new account by moving it.

1. If error.canTransfer is true, ask the user, for example: "Your Apple ID already has an active plan on another account. Move it to this account? The other account will lose it."
2. If they agree, call verify-purchase again with the same transaction and "transferToCurrentAccount": true. A 200 with "transferred": true means the plan is now on this account.
3. If they decline, send nothing more.

canTransfer is false when the plan has ended or belongs to another workspace; don't offer the move then. The server moves a plan without asking when the old account was deleted or shares this account's phone number or email.

Store setup

Done once per app by whoever administers the tenant, before purchases can be verified.

1. In App Store Connect under Users and Access → Integrations → In-App Purchase, create a key (requires the Admin role). Note the Key ID and Issuer ID, and download the .p8 file. Apple only lets you download it once.
2. Find the app's numeric Apple ID under App Information. It's different from the bundle id.
3. Save the credentials with PATCH /tenants/v1/:id/apple-config: bundleId, issuerId, keyId, privateKey (the full contents of the .p8 file) and appAppleId.
4. Under App Information → App Store Server Notifications, set both the production and sandbox URLs to https://<api-host>/webhooks/apple and choose Version 2. Webhooks live outside the /api prefix; include any deployment path prefix.
5. Create the catalog: credit packages through /pricing-config (provider apple, with iapCreditPackages) and plans through /service-entitlement-products (with platformProductIds.apple). Each product id must match App Store Connect exactly. A plan with interval monthly or annual must be an auto-renewable subscription; one_time_year must be a non-renewing subscription.
6. Choose the trial with PATCH /tenants/v1/:id/trial-config: ios.enabled turns the server trial on or off for this app, and ios.durationDays sets its length. If the App Store product has its own free-trial offer, turn the server trial off so users don't get both.

08Errors

Every error uses the same envelope. Branch on the HTTP status first, then on error.code when it's present.

{
  "statusCode": 403,
  "timestamp": "2026-10-02T09:30:00.000Z",
  "path": "/api/workflows/v1/execute",
  "error": {
    "code": "ENTITLEMENT_INACTIVE",
    "message": "Your trial has ended and no active subscription was found for this service."
  }
}

File errors on execute are 400. Show error.message as-is; {label} is the input's own label and the limits come from its fileOptions.

09Launch checklist

1. The IOS API key comes from build configuration and is never logged.
2. Tokens live in the Keychain (in a shared access group if an extension uses them), and every refresh saves the new pair before it's used.
3. Refresh goes through one actor, and 401 handling reads error.code to show the right sign-out message.
4. File inputs read fileOptions from the workflow instead of hardcoding limits, execute uses multipart, and file errors show error.message as-is.
5. Report runs use the realtime channel with a polling fallback that keeps going for at least 20 minutes.
6. Credit packages are Consumable products. Transactions are finished only after verify-purchase succeeds, and Transaction.updates and Transaction.unfinished are handled from launch.
7. The paywall is driven by canExecuteGatedWorkflow, plans and trialOffer from the server, and serverTime, not the device clock.
8. Every execute call, from the app and the Safari extension, sends X-App-Version.
9. 409 PURCHASE_LINKED_TO_ANOTHER_ACCOUNT with canTransfer: true offers to move the plan, and only retries with transferToCurrentAccount after the user agrees.
10. In-app account deletion calls DELETE /users/v1/account.