Validate Attestation

This endpoint is called automatically by the SDK. You typically don’t need to call it directly.

Request

POST /api/v1/attestation/validate

Headers

Header	Required	Description
`X-Bundle-ID`	Yes	App bundle identifier
`X-Team-ID`	Yes	Apple Developer Team ID

Body

{
  "challenge": "a1b2c3d4e5f6...",
  "keyId": "device-key-id",
  "attestationObject": "base64-encoded-attestation",
  "clientDataHash": "base64-encoded-hash",
  "bundleId": "com.yourapp.example",
  "teamId": "ABBM6U9RM5",
  "deviceModel": "iPhone15,2",
  "osVersion": "18.0",
  "appVersion": "2.1.0",
  "appBuildNumber": "42",
  "platform": "iOS",
  "deviceFingerprint": "9f2b6c..."
}

Field	Type	Required	Description
`challenge`	`string`	Yes	Challenge from the challenge endpoint
`keyId`	`string`	Yes	App Attest key identifier
`attestationObject`	`string`	Yes	Base64-encoded attestation object
`clientDataHash`	`string`	Yes	Base64-encoded client data hash
`bundleId`	`string`	Yes	App bundle identifier
`teamId`	`string`	Yes	Apple Team ID
`deviceModel`	`string`	No	Device model identifier
`osVersion`	`string`	No	OS version
`appVersion`	`string`	No	App version
`appBuildNumber`	`string`	No	Build number
`platform`	`string`	No	Platform (iOS, macOS)
`deviceFingerprint`	`string`	No	Stable hashed device fingerprint (sent by SDK 2.0.4+). Used as a secondary key for MAD counting so a device whose App Attest key is regenerated mid-month still counts once toward billing
`subjectId`	`string`	No	Opaque sharing-unit id (family/household UUID) linking this device to a subscription entitlement. Blank values are treated as absent. Also accepted on `/refresh`, where omitting it keeps the existing link. See Subscription Claims

Response

{
  "isValid": true,
  "token": "eyJhbGciOi...",
  "expiresAt": "2025-03-11T12:00:00Z",
  "deviceIntelligence": {
    "deviceId": "abc123",
    "riskScore": 12,
    "riskCategory": "trusted",
    "deviceIntegrity": "valid",
    "jailbreakDetected": false,
    "attestationCount": 5,
    "lastAttestationDate": "2025-03-09T10:00:00Z"
  },
  "customClaims": {
    "user_tier": "premium"
  }
}

Field	Type	Description
`isValid`	`boolean`	Whether the device passed attestation. Always `true` on a 200 — failures are errors, not `isValid: false`
`token`	`string`	Signed JWT token
`expiresAt`	`string`	Token expiration (ISO 8601)
`deviceIntelligence`	`object`	Device risk and integrity data — see below
`customClaims`	`object`	Your configured custom claims, flattened to strings. Nested claim objects are stringified in this map — read structured claims from the decoded JWT instead

Device intelligence

Field	Type	Description
`deviceId`	`string`	The `device_id` you passed to the challenge endpoint. A generated UUID when you passed none
`riskScore`	`integer` \| `null`	0–100. `null` on the Free tier — use `riskCategory`
`riskCategory`	`string`	`trusted` (0–20), `suspicious` (21–75), or `blocked` (76–100)
`deviceIntegrity`	`string`	`high`, `medium`, `low`, or `unknown`
`jailbreakDetected`	`boolean`	True for jailbroken devices, and for development-signed builds (Xcode installs, sideloaded IPAs)
`attestationCount`	`integer`	Attestations recorded for this device
`lastAttestationDate`	`string` \| `null`	ISO 8601 timestamp

On the Free tier only riskCategory is computed from real data; deviceIntegrity, jailbreakDetected, and attestationCount are returned as placeholders (unknown, false, 1). Upgrade to Pro or above for full device intelligence.

Errors

Error responses carry a stable code, a developer-readable error message, a requestId for support, and (where useful) a hint:

{
  "error": "Challenge expired — challenges are valid for 5 minutes. Request a new one from GET /api/v1/attestation/challenge.",
  "code": "challenge_expired",
  "hint": "See https://docs.grantiva.io/sdk/attestation#challenges for the challenge flow.",
  "requestId": "0AF2-4C61"
}

Status	Code	Meaning
400	`challenge_invalid`	Challenge not found or invalid
400	`challenge_expired`	Challenges are valid for 5 minutes and single-use
400	`challenge_already_used`	Each challenge is single-use
400	`attestation_object_invalid`	Not valid base64-encoded CBOR from `attestKey()`
400	`key_id_invalid`	Key ID must come from `DCAppAttestService.generateKey()`
400	`client_data_hash_invalid`	Must be a base64-encoded SHA256 hash of the challenge
401	`apple_validation_failed`	Cryptographic validation failed — wrong Bundle/Team ID, reused or tampered attestation, or certificate chain failure
402	`quota_exceeded`	MAD limit reached and grace period expired. Response includes `limit`, `current`, and `upgradeUrl`. Existing devices keep working — only new device onboarding is paused
409	`reattest_required`	The device’s stored key state has diverged from the server (key mismatch or signature failure). Drop local key state and re-attest — the SDK does this automatically
429	—	Rate limited. Check `Retry-After` and the `X-RateLimit-*` headers

The SDK (2.0.3+) self-heals reattest_required automatically: it clears the cached keyId and re-runs the full attestation once. You only see this error if the retry also fails.

Check a token

GET /api/v1/attestation/protected

A no-op endpoint that verifies a token end to end: it requires the identity headers plus a valid attestation JWT and echoes back what the server read from it. Useful when debugging an integration.

Headers

Header	Required	Description
`X-Bundle-ID`	Yes	App bundle identifier
`X-Team-ID`	Yes	Apple Developer Team ID
`Authorization`	Yes	`Bearer <attestation JWT>`

Response

{
  "message": "Successfully authenticated with App Attest for organization: Acme Inc",
  "userId": "device-key-id",
  "keyId": "device-key-id",
  "deviceId": "abc123"
}

Field	Type	Description
`message`	`string`	Confirmation including your organization name
`userId`	`string`	The token’s `sub` claim
`keyId`	`string`	App Attest key ID from the token
`deviceId`	`string` \| `null`	Device ID from the token, when one was set

An invalid or expired token returns 401 Unauthorized with a WWW-Authenticate header.

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Validate Attestation

Request

Headers

Body

Response

Device intelligence

Errors

Check a token

Headers

Response

​Request

​Headers

​Body

​Response

​Device intelligence

​Errors

​Check a token

​Headers

​Response

Request

Headers

Body

Response

Device intelligence

Errors

Check a token

Headers

Response