Apps

Each app is a unique Bundle ID + Team ID pair. Incoming attestations are matched to an app by these two values — no API key is involved on the client side.

App limits by tier: Free allows 2 apps, Pro allows 3, Business allows 10, Enterprise is unlimited.

Two surfaces

Surface	Auth	Covers
`/api/v1/apps`	Dashboard session (cookie)	Everything below, including per-app JWT configuration, risk thresholds, and usage stats
`/api/v1/org/apps`	API key with `apps:*` scopes, or a dashboard session	Registration and lifecycle only, with snake_case fields. See Console API

The app object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "appName": "My App",
  "bundleId": "com.yourapp.example",
  "teamId": "ABBM6U9RM5",
  "description": "Production iOS app",
  "isActive": true,
  "isPrimary": true,
  "jwtConfiguration": {
    "overrideExpirationTime": null,
    "includeAppMetadata": true,
    "customAudience": null,
    "customIssuer": null
  },
  "riskThresholds": {
    "maxAllowedRiskScore": 75,
    "blockOnJailbreak": true,
    "minAttestationCount": 0,
    "maxDeviceAge": null,
    "requireAppStoreReceipt": true
  },
  "analyticsEnabled": true,
  "webhookEnabled": true,
  "createdAt": "2026-01-15T12:00:00Z",
  "updatedAt": "2026-07-01T08:30:00Z"
}

Field	Type	Description
`isActive`	boolean	Inactive apps reject attestations
`isPrimary`	boolean	One app per org is primary; used for quick start and as the default
`jwtConfiguration`	object	Per-app JWT overrides: `overrideExpirationTime` (seconds), `includeAppMetadata`, `customAudience`, `customIssuer`
`riskThresholds`	object	Per-app risk policy: `maxAllowedRiskScore` (0–100), `blockOnJailbreak`, `minAttestationCount`, `maxDeviceAge` (days, nullable), `requireAppStoreReceipt`

List apps

GET /api/v1/apps

Returns all apps in the organization, primary app first, then alphabetically by name. Response — array of app objects.

Register an app

POST /api/v1/apps

Request body

{
  "appName": "My App",
  "bundleId": "com.yourapp.example",
  "teamId": "ABBM6U9RM5",
  "description": "Production iOS app",
  "isPrimary": false
}

Field	Type	Required	Description
`appName`	string	Yes	Display name
`bundleId`	string	Yes	App bundle identifier; validated against standard reverse-DNS format
`teamId`	string	Yes	Apple Developer Team ID
`description`	string	No	Free-form description
`isPrimary`	boolean	No	Defaults to `true` for the org’s first app, `false` otherwise. Setting it clears the flag on other apps
`jwtConfiguration`	object	No	See the app object above
`riskThresholds`	object	No	See the app object above

Response — the created app object. Errors

Status	Meaning
400	Missing name/bundle ID/team ID, or invalid bundle ID format
403	App limit for your tier reached
409	This Bundle ID + Team ID combination is already registered (globally unique)

Get an app

GET /api/v1/apps/:appID

Response — the app object. 404 if the app doesn’t exist in your organization.

Update an app

PUT /api/v1/apps/:appID

All fields optional; only provided fields change. Bundle ID and Team ID cannot be changed — register a new app instead. Request body

{
  "appName": "My App (renamed)",
  "description": "Updated description",
  "isActive": true,
  "jwtConfiguration": { "includeAppMetadata": false },
  "riskThresholds": { "maxAllowedRiskScore": 60, "blockOnJailbreak": true, "minAttestationCount": 0, "requireAppStoreReceipt": true },
  "analyticsEnabled": true,
  "webhookEnabled": false
}

Response — the updated app object.

Delete an app

DELETE /api/v1/apps/:appID

Permanently removes the app. If the deleted app was primary, another active app is promoted to primary automatically. Response — 204 No Content Errors

Status	Meaning
403	Cannot delete the last remaining app
404	App not found

Activate / deactivate

POST /api/v1/apps/:appID/activate
POST /api/v1/apps/:appID/deactivate

Toggles whether the app accepts attestations. The primary app cannot be deactivated (403). Response — the updated app object.

Set primary

POST /api/v1/apps/:appID/set-primary

Makes this app the organization’s primary app and clears the flag on all others. The app must be active (403 otherwise). Response — the updated app object.

Usage stats (all apps)

GET /api/v1/apps/stats

Returns aggregate usage per app. Response

[
  {
    "appId": "550e8400-e29b-41d4-a716-446655440000",
    "appName": "My App",
    "totalAttestations": 128341,
    "uniqueDevices": 20419,
    "avgRiskScore": 11.4,
    "successRate": 0.996,
    "lastAttestation": "2026-07-26T11:59:31Z"
  }
]

Usage detail (single app)

GET /api/v1/apps/:appID/usage

Query parameters

Parameter	Default	Description
`days`	30	Look-back window for daily usage

Response

{
  "appId": "550e8400-e29b-41d4-a716-446655440000",
  "appName": "My App",
  "dailyUsage": [
    {
      "date": "2026-07-26T00:00:00Z",
      "attestations": 4211,
      "unique_devices": 3980,
      "avg_risk_score": 10.7
    }
  ],
  "topDevices": [
    {
      "keyId": "abc123keyid",
      "attestationCount": 812,
      "riskScore": 4,
      "lastSeen": "2026-07-26T11:12:00Z",
      "deviceModel": "iPhone16,2"
    }
  ],
  "recentErrors": [
    {
      "timestamp": "2026-07-26T09:30:00Z",
      "errorReason": "Challenge expired",
      "keyId": "def456keyid"
    }
  ]
}

dailyUsage is sorted newest-day first; topDevices is the 10 devices with the most attestations; recentErrors is the 10 most recent failed attestation events.

Console API

/api/v1/org/apps covers app registration and lifecycle for the CLI and scripts. It accepts an API key (Authorization: Bearer gpat_…/aat_…) as well as a dashboard session, and its wire format is snake_case.

Operation	Key scope	Session role
Read	`apps:read`	viewer+
Write	`apps:write`	admin+
Delete	`apps:delete`	admin+

:appRef accepts either the app’s UUID or its bundle ID (resolved within your organization). An unknown reference — including one belonging to another organization — returns 404.

The console app object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "app_name": "My App",
  "bundle_id": "com.yourapp.example",
  "team_id": "ABBM6U9RM5",
  "description": "Production iOS app",
  "is_active": true,
  "is_primary": true,
  "analytics_enabled": true,
  "webhook_enabled": true,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-07-01T08:30:00Z"
}

JWT configuration and risk thresholds are not part of this surface — use /api/v1/apps for those.

Endpoints

Method	Path	Notes
`GET`	`/api/v1/org/apps`	Array of app objects, primary first, then oldest first
`POST`	`/api/v1/org/apps`	`201 Created` with the new app
`GET`	`/api/v1/org/apps/:appRef`	One app object
`PUT`	`/api/v1/org/apps/:appRef`	Partial update
`DELETE`	`/api/v1/org/apps/:appRef`	`{ "deleted": true, "id": "…" }`
`POST`	`/api/v1/org/apps/:appRef/activate`	Updated app object
`POST`	`/api/v1/org/apps/:appRef/deactivate`	Updated app object
`POST`	`/api/v1/org/apps/:appRef/set-primary`	Updated app object

Create

curl -X POST https://api.grantiva.io/api/v1/org/apps \
  -H "Authorization: Bearer aat_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "My App",
    "bundle_id": "com.yourapp.example",
    "team_id": "ABBM6U9RM5",
    "description": "Production iOS app",
    "is_primary": false
  }'

Field	Type	Required	Description
`app_name`	string	Yes	Display name
`bundle_id`	string	Yes	Reverse-DNS bundle identifier
`team_id`	string	Yes	Apple Developer Team ID
`description`	string	No	Free-form description
`is_primary`	boolean	No	Defaults to `true` for the org’s first app, `false` otherwise

Update

Only app_name, description, analytics_enabled, and webhook_enabled can change. Bundle ID and Team ID are immutable. A body with none of these returns 400.

{
  "app_name": "My App (renamed)",
  "description": "Updated description",
  "analytics_enabled": true,
  "webhook_enabled": false
}

Errors

Status	Meaning
400	Missing or empty name/bundle ID/team ID, invalid bundle ID format, or an update with no updatable fields
403	App limit for your tier reached; deleting the last app; deleting or deactivating the primary app; setting an inactive app primary; or the key lacks the required scope
404	No app matches `:appRef` in your organization
409	This Bundle ID + Team ID combination is already registered (globally unique)

Deletion rules differ between the two surfaces. /api/v1/org/apps refuses to delete the primary app while other apps exist — set another app primary first. /api/v1/apps deletes it and promotes another app automatically.

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Two surfaces

The app object

List apps

Register an app

Get an app

Update an app

Delete an app

Activate / deactivate

Set primary

Usage stats (all apps)

Usage detail (single app)

Console API

The console app object

Endpoints

Create

Update

Errors

​Two surfaces

​The app object

​List apps

​Register an app

​Get an app

​Update an app

​Delete an app

​Activate / deactivate

​Set primary

​Usage stats (all apps)

​Usage detail (single app)

​Console API

​The console app object

​Endpoints

​Create

​Update

​Errors

Two surfaces

The app object

List apps

Register an app

Get an app

Update an app

Delete an app

Activate / deactivate

Set primary

Usage stats (all apps)

Usage detail (single app)

Console API

The console app object

Endpoints

Create

Update

Errors