Custom Claims

Custom claims let you embed additional data in the JWT returned by attestation. Your backend reads these claims to make authorization decisions without extra API calls.

Claim types

Type	Description	Example
Static	Fixed value for all devices	`"app_version": "2.0"`
Conditional	Value based on device properties	Risk score > 50 → `"restricted": true`
Dynamic	Computed from expressions	`"days_since_first_seen": 42`
External	Fetched from your API at attestation time	User subscription status

External claims are available on Enterprise plans only.

subscription is a reserved claim key, managed by Grantiva’s subscription entitlement ingestion. Creating a custom claim named subscription returns a 400.

Managing claims

Claims are managed from the dashboard or via the API.

Dashboard

Go to Settings > Custom Claims to create, edit, reorder, and test claims.

API

# Create a claim
curl -X POST https://api.grantiva.io/api/v1/claims \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "claimKey": "user_tier",
    "claimName": "User Tier",
    "claimType": "static",
    "dataType": "string",
    "staticValue": "premium"
  }'

Reading claims

Claims appear in the attestation result:

let result = try await grantiva.validateAttestation()

if let tier = result.customClaims["user_tier"] as? String {
    print("User tier: \(tier)")
}

And in the decoded JWT on your backend:

{
  "custom_claims": {
    "user_tier": "premium",
    "restricted": false
  }
}

Tier limits

Tier	Max claims
Free	1 (static only)
Pro	5
Business	10
Enterprise	20

Testing claims

Use the claim test endpoint to preview how a claim evaluates without performing a real attestation:

curl -X POST https://api.grantiva.io/api/v1/claims/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "claimConfiguration": { "claimKey": "test", "claimType": "conditional", ... },
    "testContext": {
      "deviceProfile": { "riskScore": 75, "jailbreakDetected": true }
    }
  }'

Getting Started

iOS SDK

CLI

Concepts

Push

Dashboard

Claim types

Managing claims

Dashboard

API

Reading claims

Tier limits

Testing claims

​Claim types

​Managing claims

​Dashboard

​API

​Reading claims

​Tier limits

​Testing claims

Claim types

Managing claims

Dashboard

API

Reading claims

Tier limits

Testing claims