Testing Your Integration

After adding the SDK and calling validateAttestation(), you need to know whether it is actually working. This guide walks through what to look for on both the iOS Simulator and a physical device, what a successful response looks like, and how to diagnose common errors.

Physical device required for full attestation. The iOS Simulator cannot run App Attest because it has no Secure Enclave. If you are developing in the Simulator, see Simulator Setup to configure API key fallback first.

Quick verification checklist

Run through these five checks after your first validateAttestation() call:

result.isValid is true

The most basic check. If false, the device did not pass attestation.

let result = try await grantiva.validateAttestation()
print(result.isValid) // true

result.token is a non-empty string

A JWT was issued. It should begin with eyJ (base64-encoded JSON header).

print(result.token.prefix(10)) // "eyJhbGciOi"

riskScore is present (if on Pro or above)

On a physical device with a Pro+ plan, riskScore is a non-nil integer between 0 and 100. On the Free tier or in the Simulator, it will be nil.

print(result.deviceIntelligence.riskScore) // Optional(12)

A score of nil on a physical device with a Pro plan indicates an issue — see riskScore is nil on a real device below. riskCategory is populated on every plan, so use it when you only need the band.

You got a real JWT, not the API key placeholder

In API key mode the SDK skips App Attest entirely and hands back the literal placeholder string simulator-dev-token instead of a JWT.

print(result.token == "simulator-dev-token") // false on a real attestation

If this is true on a physical device, the SDK fell back to API key auth — check that your production initialization does not pass an apiKey.

Your app appears in the Grantiva dashboard

Open Dashboard → Analytics → Devices. You should see a new attestation event. If nothing appears after 30 seconds, the request may not be reaching the server — check network errors below.

What the response looks like

Physical device (full attestation)

result.isValid                              // true
result.token                                // "eyJhbGciOiJFUzI1NiIsInR5..."
result.expiresAt                            // 2026-03-21 14:00:00 UTC (1 hour out by default)

result.deviceIntelligence.deviceId          // "d3f1a2b4-..."
result.deviceIntelligence.riskScore         // Optional(8)  (0–100; nil on Free tier)
result.deviceIntelligence.riskCategory      // RiskCategory.trusted
result.deviceIntelligence.deviceIntegrity   // "uncompromised"
result.deviceIntelligence.jailbreakDetected // false
result.deviceIntelligence.attestationCount  // 1
result.customClaims                         // ["plan": "pro", "env": "production"]

customClaims values arrive as strings, whatever type you configured in the dashboard.

Simulator (API key fallback)

The SDK does not contact the attestation endpoint at all in API key mode. It returns a synthetic result built on-device, so these values are fixed:

result.isValid                              // true
result.token                                // "simulator-dev-token"  (a placeholder, not a JWT)
result.expiresAt                            // one year out

result.deviceIntelligence.deviceId          // the SDK's local device identifier
result.deviceIntelligence.riskScore         // nil        (not computed without hardware attestation)
result.deviceIntelligence.riskCategory      // RiskCategory.trusted
result.deviceIntelligence.deviceIntegrity   // "api_key_mode"
result.deviceIntelligence.jailbreakDetected // false
result.deviceIntelligence.attestationCount  // 0
result.customClaims                         // [:]

Flag and feedback requests made in this mode authenticate with the API key rather than the token.

Sample JWT payload

After decoding the token (Base64URL-decode the middle segment), you will see something like this:

{
  "sub": "AbCdEf01...",
  "kid": "AbCdEf01...",
  "iss": "api.grantiva.io",
  "aud": "com.example.MyApp",
  "iat": 1742385600,
  "exp": 1742389200,
  "device_id": "d3f1a2b4-8c3e-4f2a-9b1d-5e7f8a2c4d6e",
  "bundle_id": "com.example.MyApp",
  "team_id": "ABCDE12345",
  "device_integrity": "uncompromised",
  "attestation_count": 1,
  "risk_score": 8,
  "device_model": "iPhone15,2",
  "os_version": "18.0",
  "app_version": "1.4.0",
  "first_seen": 1742299200,
  "last_attestation": 1742385600,
  "jailbreak_detected": false,
  "custom_claims": { "plan": "pro" }
}

Claims always present:

Claim	Type	Description
`sub` / `kid`	string	The device’s App Attest key ID
`iss`	string	Issuer — `api.grantiva.io`
`aud`	string	Your Bundle ID
`iat` / `exp`	number	Issued at / expiry (Unix timestamps)
`device_id`	string	Grantiva’s identifier for this device
`bundle_id`	string	Your app’s Bundle ID
`team_id`	string	Your Apple Team ID

Claims present on Pro and above:

Claim	Type	Description
`risk_score`	number	0–100 integer
`device_integrity`	string	Integrity status for the device
`attestation_count`	number	Lifetime attestation count for this device
`jailbreak_detected`	boolean	Whether jailbreak signals were detected
`device_model`, `os_version`, `app_version`	string	Reported by the SDK at attestation time
`first_seen`, `last_attestation`	number	Unix timestamps

Free-tier tokens carry only the always-present claims plus custom_claims. The numeric risk_score is withheld, but riskCategory is still returned on the AttestationResult. Custom claims — claims you configure in the dashboard are nested under the custom_claims object, not merged into the top level.

Risk score reference

The SDK’s RiskCategory has three cases. The dashboard splits the middle band further for its histograms, but the SDK and JWT only ever use these three:

Score	`RiskCategory`	Dashboard bucket	Suggested action
0–20	`.trusted`	low	Proceed normally
21–50	`.suspicious`	medium	Monitor — consider step-up verification
51–75	`.suspicious`	high	Challenge — require additional confirmation
76–100	`.blocked`	critical	Block — device likely compromised

Common errors and fixes

`deviceNotSupported`

Cause: App Attest is unavailable on this device — for example, hardware without a Secure Enclave or a region where App Attest is restricted. Fix: Gate attestation-required flows so they aren’t reached on unsupported hardware, or fall back to a non-attested code path.

catch GrantivaError.deviceNotSupported {
    // Hardware does not support App Attest
}

`simulatorAPIKeyRequired`

Cause: validateAttestation() was called in the iOS Simulator without an API key. App Attest is unavailable in the Simulator, so the SDK requires an API key fallback. Fix: Pass an apiKey parameter during initialization for Simulator builds:

#if targetEnvironment(simulator)
let grantiva = Grantiva(teamId: "YOUR_TEAM_ID", apiKey: "gpat_your_dev_key")
#else
let grantiva = Grantiva(teamId: "YOUR_TEAM_ID")
#endif

Get a development API key from Dashboard → Settings → API Keys. See Simulator Setup for the full fallback flow.

`configurationError`

Cause: The Team ID you passed to Grantiva(teamId:) does not match the Bundle ID of the running app, or the app is not registered in the Grantiva dashboard. Fix:

Verify your Team ID in the Apple Developer portal under Membership.
Confirm the Bundle ID in Xcode matches what you registered in the dashboard under Apps.
Check that the teamId string has no extra whitespace.

`networkError`

Cause: The SDK could not reach api.grantiva.io. Common causes: no internet connection, App Transport Security (ATS) misconfiguration, VPN interference, or the challenge request timing out. Fix:

Confirm the device has internet access.
Check that your Info.plist does not block outbound HTTPS to api.grantiva.io.
In development, check the device is not behind a proxy that intercepts TLS.
The SDK retries automatically — if networkError is consistently thrown, check the status page.

`validationFailed`

Cause: The Grantiva server rejected the attestation. This usually means the attestation object was malformed, the challenge expired before the SDK submitted it, or the device’s App Attest key is corrupted. Fix:

Call grantiva.clearStoredData() to wipe the cached key and token, then retry.
If the problem persists across retries on the same device, the device’s App Attest key may need to be regenerated — this happens automatically after clearStoredData().

catch GrantivaError.validationFailed {
    // Force key regeneration
    grantiva.clearStoredData()
    let result = try await grantiva.validateAttestation()
}

`challengeExpired`

Cause: Challenges are single-use and expire 5 minutes after issue. Pausing in the debugger mid-attestation, a badly skewed device clock, or a very slow network can outlive the challenge. Fix: The SDK requests a fresh challenge and retries. If this error reaches your code, the retry also failed. Check for:

Device clock sync issues (Settings → General → Date & Time → Set Automatically)
A breakpoint sitting between generateKey and the /validate call
Network latency pushing attestation submission past 5 minutes

`rateLimited`

Cause: Your tenant has exceeded the request rate limit, or this device has submitted too many attestation requests in a short window. Fix: The SDK includes backoff-aware retry logic. If rateLimited surfaces to your code:

Ensure you are not calling validateAttestation() in a tight loop — let the SDK handle caching.
If you see this in production at scale, contact support to review your plan limits.

`tokenExpired` returned by your backend

Cause: The JWT is issued with a 1-hour TTL by default. Your backend received a token that has already expired. The SDK treats its cached token as expired 5 minutes early, so a genuinely expired token usually means the app held onto it rather than re-reading it. Fix: Call refreshToken() before sending the token to your backend, or catch the expired state in your backend and prompt the client to re-attest:

// Check before making an API call
if !grantiva.isTokenValid() {
    let result = try await grantiva.refreshToken()
    // Use result.token
}

`riskScore` is nil on a real device

Cause: One of:

Your account is on the Free tier — the numeric score requires Pro or above. riskCategory is still populated.
The SDK is in API key mode, so no attestation happened.
The result came from refreshToken() on a still-valid token, which returns placeholder device intelligence rather than re-reading it from the server.

Fix:

Check your plan in Dashboard → Settings → Billing.
Confirm result.deviceIntelligence.riskScore is nil specifically (not 0) — a score of 0 is a valid low-risk score, not an error.
Confirm result.token != "simulator-dev-token" and that you are not passing an apiKey on device builds.
Read device intelligence from a validateAttestation() result, not a refreshToken() one.

Next steps

Backend JWT verification

Verify the token server-side and read device claims in Node.js, Python, or Go.

Error handling reference

Full list of GrantivaError cases with suggested handling.

Risk scoring concepts

How risk scores are computed and how to set thresholds.

Simulator setup

Configure API key fallback for development builds.

Getting Started

SDKs

CLI

Concepts

Push

Dashboard

Testing Your Integration

Quick verification checklist

What the response looks like

Physical device (full attestation)

Simulator (API key fallback)

Sample JWT payload

Risk score reference

Common errors and fixes

`deviceNotSupported`

`simulatorAPIKeyRequired`

`configurationError`

`networkError`

`validationFailed`

`challengeExpired`

`rateLimited`

`tokenExpired` returned by your backend

`riskScore` is nil on a real device

Next steps

Backend JWT verification

Error handling reference

Risk scoring concepts

Simulator setup

​Quick verification checklist

​What the response looks like

​Physical device (full attestation)

​Simulator (API key fallback)

​Sample JWT payload

​Risk score reference

​Common errors and fixes

​deviceNotSupported

​simulatorAPIKeyRequired

​configurationError

​networkError

​validationFailed

​challengeExpired

​rateLimited

​tokenExpired returned by your backend

​riskScore is nil on a real device

​Next steps

Backend JWT verification

Error handling reference

Risk scoring concepts

Simulator setup

Quick verification checklist

What the response looks like

Physical device (full attestation)

Simulator (API key fallback)

Sample JWT payload

Risk score reference

Common errors and fixes

`deviceNotSupported`

`simulatorAPIKeyRequired`

`configurationError`

`networkError`

`validationFailed`

`challengeExpired`

`rateLimited`

`tokenExpired` returned by your backend

`riskScore` is nil on a real device

Next steps