Attestation

​

Validate a device

let result = try await grantiva.validateAttestation()

1. Requests a one-time challenge from the server
2. Generates or retrieves an attestation key via Apple’s App Attest
3. Creates an attestation object on-device
4. Sends it to the Grantiva server for validation
5. Returns a signed JWT with device intelligence

​

AttestationResult

result.isValid              // Bool — whether the device passed
result.token                // String — signed JWT token
result.expiresAt            // Date — token expiration
result.deviceIntelligence   // DeviceIntelligence
result.customClaims         // [String: Any] — your custom JWT claims

​

DeviceIntelligence

result.deviceIntelligence.deviceId            // String — unique device ID
result.deviceIntelligence.riskScore           // Int? — 0–100 (Pro and above); nil on Free tier and in API key mode
result.deviceIntelligence.riskCategory        // RiskCategory — .trusted, .suspicious, or .blocked (all tiers)
result.deviceIntelligence.deviceIntegrity     // String — integrity status
result.deviceIntelligence.jailbreakDetected   // Bool
result.deviceIntelligence.attestationCount    // Int — total attestations from this device
result.deviceIntelligence.lastAttestationDate // Date?

​

Token caching

// First call — full attestation flow
let result1 = try await grantiva.validateAttestation()

// Second call — returns cached token instantly
let result2 = try await grantiva.validateAttestation()

​

Refresh tokens

if let result = try await grantiva.refreshToken() {
    // Token is valid or was refreshed
    print(result.token)
}

​

Check token status

// Synchronous check — does a valid token exist?
if grantiva.isTokenValid() {
    let token = grantiva.getCurrentToken()
    // Use token in API requests
}

​

Clear stored data

grantiva.clearStoredData()

​

Background activity

• Usage heartbeat — a fire-and-forget ping every 120 seconds while the app is running, used for Monthly Active Device counting.
• Flag streaming — a Server-Sent Events connection for live feature flag updates. On iOS the SDK stops it when the app backgrounds and restarts it on foreground.

​

Use the token

var request = URLRequest(url: yourAPIEndpoint)
request.setValue("Bearer \(result.token)", forHTTPHeaderField: "Authorization")

• Device risk score
• Jailbreak detection status
• Device model and OS version
• Custom claims configured in the dashboard

​

Challenges

• Challenges are valid for 5 minutes. A slow attestation flow (e.g. paused in the debugger) can outlive its challenge — the server returns challenge_expired and the SDK requests a fresh one.
• Challenges are single-use. Replaying a challenge returns challenge_already_used. Never cache or share challenges between attestation attempts.
• The clientDataHash sent to Apple must be the SHA256 of the exact challenge string. A mismatch surfaces as client_data_hash_invalid.

​

Troubleshooting

1. Bundle ID / Team ID mismatch — the values in the request don’t match what App Attest signed against. Check that the SDK’s teamId matches your Apple Developer Team ID and the build’s bundle identifier is registered in the dashboard.
2. Running in the Simulator — App Attest only works on real hardware. Use API key mode for Simulator and CI builds.
3. Reused or tampered attestation object — attestation objects are single-use and bound to their challenge.
4. Key state drift (reattest_required, HTTP 409) — the device’s stored App Attest key no longer matches the server’s records (backup restore, device transfer). The SDK self-heals by clearing local key state and re-attesting; you’ll only see the error if that retry also fails.
5. MAD limit reached (HTTP 402) — new device onboarding is paused because your plan’s Monthly Active Device limit was exceeded and the grace period ended. See Billing.

​

Error handling

do {
    let result = try await grantiva.validateAttestation()
} catch GrantivaError.simulatorAPIKeyRequired {
    // Running in Simulator without an API key — see Simulator Setup
} catch GrantivaError.deviceNotSupported {
    // Hardware/region does not support App Attest
} catch GrantivaError.networkError(let error) {
    // Network issue — retry later
} catch GrantivaError.validationFailed {
    // Device failed attestation — potentially compromised
} catch GrantivaError.challengeExpired {
    // Challenge timed out — retry automatically
} catch {
    print(error.localizedDescription)
}

​

Backend verification