Organization Settings

Authentication

Most endpoints on this page accept either a dashboard session cookie or a server API key sent as Authorization: Bearer <key>. A few need a real session and are marked session only.

Endpoint	Session role	Key scope
`GET /api/v1/org/settings`	Any member	`org:read`
`PUT /api/v1/org/settings`	Admin	`org:write`
`GET /api/v1/org/notification-preferences`	Any member	`org:read`
`PATCH /api/v1/org/notification-preferences`	Admin	`org:write`
`GET /api/v1/org/usage`	Any member	`org:read`
`GET /api/v1/org/billing`	Admin	`admin:billing`
`GET /api/v1/org/audit-log`	Admin	`admin:audit`
`POST /api/v1/org/billing/portal-session`	Admin	Session only
`GET /api/v1/org/quickstart-snippet`	Any member	Session only
`DELETE /api/v1/org`	Owner	Session only
`DELETE /api/v1/account`	Owner	Session only

Roles, lowest to highest: Viewer, Member, Admin, Owner.

admin:billing and admin:audit are Enterprise-only scopes, so on other plans billing and the audit log are reachable with a dashboard session but not with an API key.

Get organization settings

GET /api/v1/org/settings

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "serviceTier": "Business",
  "serviceTierRawValue": "professional",
  "billingEmail": "billing@acme.com",
  "createdAt": "2026-01-15T12:00:00Z",
  "updatedAt": "2026-07-01T08:30:00Z"
}

Field	Type	Description
`serviceTier`	string	Plan display name: `Free`, `Pro`, `Business`, or `Enterprise`. Show this one
`serviceTierRawValue`	string	Internal tier identifier. Some organizations carry historical identifiers that no longer match the display name — never branch on this value
`billingEmail`	string \| null	Billing contact, if set

Update organization settings

PUT /api/v1/org/settings

Currently only the organization name can be changed; the URL slug is regenerated from the new name. An empty or whitespace-only name is ignored. Request body

{
  "name": "Acme Corporation"
}

Response — 200 OK — the updated settings object.

Usage

GET /api/v1/org/usage

The canonical Monthly Active Devices (MAD) meter for the organization. Values are cached for up to 5 minutes. Response

{
  "currentMAD": 48211,
  "tierLimit": 250000,
  "tierName": "Business",
  "billingPeriodStart": "2026-07-01T00:00:00Z",
  "billingPeriodEnd": "2026-08-01T00:00:00Z",
  "usagePercent": 19.3,
  "daysUntilReset": 6,
  "resetDate": "2026-08-01"
}

Field	Type	Description
`currentMAD`	integer	Unique devices that attested at least once this billing period
`tierLimit`	integer \| null	MAD cap for the plan; `null` on Enterprise (unlimited)
`tierName`	string	Plan display name
`usagePercent`	number \| null	Percentage of the cap consumed, one decimal; `null` when unlimited
`daysUntilReset`	integer \| null	Calendar days until the period resets
`resetDate`	string \| null	`YYYY-MM-DD` of the next reset (UTC)

Notification preferences

Get preferences

GET /api/v1/org/notification-preferences

Response

{
  "newFeatureRequest": true,
  "featureVoteThreshold": true,
  "featureVoteThresholdCount": 10,
  "featureStatusChange": true,
  "newSupportTicket": true,
  "ticketAdminReply": true,
  "ticketResolved": true,
  "ticketUserReply": true,
  "flagToggle": true,
  "teamInvite": true,
  "usageAlert": true
}

Update preferences

PATCH /api/v1/org/notification-preferences

Partial update — only fields present in the body are modified.

Field	Type	Description
`newFeatureRequest`	boolean	Notify when a feature request is filed
`featureVoteThreshold`	boolean	Notify when a feature request crosses the vote threshold
`featureVoteThresholdCount`	integer	Vote threshold, 1–10000
`featureStatusChange`	boolean	Notify on feature request status changes
`newSupportTicket`	boolean	Notify on new support tickets
`ticketAdminReply`	boolean	Notify when support replies to a ticket
`ticketResolved`	boolean	Notify when a ticket is resolved
`ticketUserReply`	boolean	Notify when a user replies to a ticket
`flagToggle`	boolean	Notify when a feature flag is toggled
`teamInvite`	boolean	Notify the inviter when an invite is accepted
`usageAlert`	boolean	Notify on usage/quota alerts

Response — 200 OK — the full updated preferences object. Errors

Status	Meaning
400	`featureVoteThresholdCount` outside 1–10000

Billing

Get billing summary

GET /api/v1/org/billing

Response

{
  "plan": "Business",
  "planRawValue": "professional",
  "madUsed": 48211,
  "madLimit": 250000,
  "currentPeriodEnd": "2026-08-01T00:00:00Z",
  "stripeCustomerId": "cus_ABC123",
  "stripeSubscriptionId": "sub_XYZ789"
}

Field	Type	Description
`plan`	string	Plan display name
`planRawValue`	string	Internal tier identifier — display `plan` instead
`madUsed`	integer	Unique devices that attested since the start of the current calendar month
`madLimit`	integer \| null	Plan MAD limit; `null` means unlimited (Enterprise)
`currentPeriodEnd`	string \| null	End of the current billing period
`stripeCustomerId`	string \| null	Present once the org has upgraded to a paid plan
`stripeSubscriptionId`	string \| null	Active Stripe subscription, if any

madUsed here counts from the start of the calendar month. GET /api/v1/org/usage is the canonical meter and reports the org’s billing period.

Create a billing portal session

POST /api/v1/org/billing/portal-session

Session only. Requires Admin role. Returns a short-lived, pre-authenticated Stripe Customer Portal URL where the user can view invoices, download receipts, and update the payment method. Open it directly in the browser. Response — 200 OK

{
  "url": "https://billing.stripe.com/p/session/..."
}

Errors

Status	Meaning
402	No billing account — the org has never upgraded to a paid plan
503	Billing portal not configured; contact billing@grantiva.io

Audit log

GET /api/v1/org/audit-log

Paginated audit trail scoped to the current organization, newest first. Query parameters

Parameter	Default	Description
`page`	1	Page number
`per`	50	Items per page (max 100)

Response

{
  "items": [
    {
      "id": "7f3e2a10-1b2c-4d5e-8f90-112233445566",
      "actorEmail": "admin@acme.com",
      "action": "apikey.created",
      "resourceType": "api_key",
      "resourceId": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": { "name": "Analytics pipeline" },
      "ipAddress": "203.0.113.7",
      "createdAt": "2026-07-26T12:00:00Z"
    }
  ],
  "metadata": {
    "page": 1,
    "per": 50,
    "total": 320
  }
}

metadata on an entry is a flat string map, or null. Actions follow a resource.verb convention, for example:

Action	Recorded when
`user.login`, `user.cli_login`, `user.cli_authorized`	Sign-in and CLI authorization
`invite.created`, `invite.revoked`, `member.removed`	Team changes
`apikey.created`, `apikey.rotated`, `apikey.revoked`	API key lifecycle
`webhook.created`, `webhook.updated`, `webhook.deleted`, `webhook.delivery_retry`	Webhook changes
`risk_alert_rule.created`, `risk_alert_rule.updated`, `risk_alert_rule.deleted`	Risk alert rules
`release_note.created`, `release_note.published`, `release_note.unpublished`, `release_note.deleted`	Release notes
`org.settings_updated`, `org.notification_preferences_updated`, `org.entitlement_config_updated`	Organization settings

Quick start snippet

GET /api/v1/org/quickstart-snippet

Session only. Returns the org’s primary app credentials and a pre-filled Swift SDK initialization snippet, used by the dashboard’s quick start page. Response

{
  "appId": "550e8400-e29b-41d4-a716-446655440000",
  "appName": "My App",
  "teamId": "ABBM6U9RM5",
  "bundleId": "com.yourapp.example",
  "swiftSnippet": "import Grantiva\n..."
}

Errors

Status	Meaning
404	No apps registered yet

Delete the organization

DELETE /api/v1/org

Session only. Requires Owner role.

This permanently and immediately deletes the organization and all associated data in a single transaction — apps, devices, attestations, challenges, API keys, webhooks and deliveries, feature flags and rules, custom claims, audit logs, heartbeats, support tickets, feature requests and votes, invites, and memberships. Member user accounts are deactivated and suspended. This cannot be undone.

The caller’s session is destroyed as part of the request. Response — 204 No Content

Delete your account

DELETE /api/v1/account

Session only. Requires Owner role. Soft-deletes the current user’s account:

The account is marked pending deletion and hard-deleted after 30 days. Contact support@grantiva.io before then to cancel.
Any active Stripe subscription is cancelled.
A confirmation email is sent with the scheduled deletion date.
The current session is destroyed.

Response — 204 No Content Errors

Status	Meaning
409	The organization has other members — remove them or transfer ownership first

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Organization Settings

Authentication

Get organization settings

Update organization settings

Usage

Notification preferences

Get preferences

Update preferences

Billing

Get billing summary

Create a billing portal session

Audit log

Quick start snippet

Delete the organization

Delete your account

See also

​Authentication

​Get organization settings

​Update organization settings

​Usage

​Notification preferences

​Get preferences

​Update preferences

​Billing

​Get billing summary

​Create a billing portal session

​Audit log

​Quick start snippet

​Delete the organization

​Delete your account

​See also

Authentication

Get organization settings

Update organization settings

Usage

Notification preferences

Get preferences

Update preferences

Billing

Get billing summary

Create a billing portal session

Audit log

Quick start snippet

Delete the organization

Delete your account

See also