API Keys

Server API keys are available on Pro and above. The number of active keys is limited by tier: Pro allows 1, Business allows 5, Enterprise allows 20. The Free tier cannot create API keys.

Authentication

These endpoints accept either a dashboard session cookie or a server API key sent as Authorization: Bearer <key>.

Endpoint	Session role	Key scope
`GET /api/v1/org/api-keys`	Any member	`keys:read`
`POST /api/v1/org/api-keys`	Admin	`keys:write`
`POST /api/v1/org/api-keys/:id/rotate`	Admin	`keys:write`
`POST`/`DELETE` revoke	Admin	`keys:write`

Key-authenticated requests are authorized by scope, not by org role. A key may only mint keys with scopes it holds itself — requesting more returns 403.

Org endpoints read the key from Authorization: Bearer only. The X-API-Key header works on the SDK and VRT surfaces, not here.

Key prefixes

Grantiva issues three kinds of keys, distinguishable by prefix:

Prefix	Type	Issued by
`grantiva_prod_sk_`	Server API key with scopes	This endpoint (`POST /api/v1/org/api-keys`)
`aat_`	Organization/tenant key	Provisioned with the organization
`gpat_`	Personal access token tied to a user	CLI login — always full access (`api:all`)

Use keys in server-to-server requests via the Authorization header:

Authorization: Bearer grantiva_prod_sk_...

The raw key is returned only once, at creation or rotation time. Only a SHA-256 hash is stored — a lost key cannot be recovered, only rotated.

Key-authenticated requests are rate limited in the apikey bucket — see API Conventions.

List API keys

GET /api/v1/org/api-keys

Returns all API keys for the organization (including revoked ones), sorted by creation date, newest first. Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Analytics pipeline",
    "keyPrefix": "grantiva_prod_sk_1a2b3c4d5e6f7a8b...",
    "scopes": ["analytics:read", "devices:read"],
    "keyType": "org",
    "isActive": true,
    "lastUsedAt": "2026-07-20T09:15:00Z",
    "expiresAt": null,
    "createdAt": "2026-05-01T12:00:00Z"
  }
]

Field	Type	Description
`id`	string (UUID)	Key identifier
`name`	string	Human-readable label
`keyPrefix`	string	Truncated key for identification — never the full key
`scopes`	string[]	Granted scopes (see below)
`keyType`	string \| null	`org` or `personal`
`isActive`	boolean	`false` once revoked
`lastUsedAt`	string \| null	Last successful authentication with this key
`expiresAt`	string \| null	Expiration timestamp, if set
`createdAt`	string	Creation timestamp

Create an API key

POST /api/v1/org/api-keys

Request body

{
  "name": "Analytics pipeline",
  "scopes": ["analytics:read", "devices:read"],
  "expiresAt": "2027-01-01T00:00:00Z"
}

Field	Type	Required	Description
`name`	string	Yes	Label shown in the dashboard, 1–100 characters
`scopes`	string[]	Yes	At least one scope. Any unrecognized scope string rejects the whole request
`expiresAt`	string	No	ISO 8601 expiration date. Omit for a non-expiring key

Response — 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Analytics pipeline",
  "keyPrefix": "grantiva_prod_sk_1a2b3c4d5e6f7a8b...",
  "rawKey": "grantiva_prod_sk_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "scopes": ["analytics:read", "devices:read"],
  "keyType": null,
  "isActive": true,
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-07-26T12:00:00Z"
}

rawKey is shown only in this response. Store it securely. Errors

Status	Meaning
400	Unknown scope string, no scopes, name missing or over 100 characters, invalid `expiresAt` format, scopes not available on your tier, or the active-key limit for your tier is reached
403	Session caller is not an Admin, or a key caller asked for scopes it does not itself hold

Rotate an API key

POST /api/v1/org/api-keys/:id/rotate

Generates a new key with the same scopes, expiration, and IP allow-list. The new key is named "<old name> (Rotated)". Rotation does not re-check tier scope availability — an existing key keeps exactly the access it had. Request body (optional)

{
  "gracePeriodDays": 7
}

Field	Type	Required	Description
`gracePeriodDays`	integer	No	If provided and greater than 0, the old key keeps working for this many days (its name gets an `(Expires Soon)` suffix). If omitted or 0, the old key is deactivated immediately

Response — 200 OK Same shape as the create response, including the new rawKey (shown once). Errors

Status	Meaning
400	The new key would exceed the active-key limit for your tier
404	Key not found in this organization, or already revoked

Revoke an API key

POST /api/v1/org/api-keys/:id/revoke
DELETE /api/v1/org/api-keys/:id

Both routes are equivalent. The key is deactivated immediately and cannot be reactivated. Response — 204 No Content Errors

Status	Meaning
404	Key not found in this organization

Scopes

Scopes follow a resource:action format. A key with api:all passes every scope check.

Scope	Description
`analytics:read`	View attestation analytics and reports
`analytics:export`	Export analytics data
`analytics:realtime`	Access real-time analytics streams
`devices:read`	View device profiles and attestation history
`devices:write`	Update device metadata or risk scores
`devices:delete`	Remove device records (GDPR compliance)
`claims:read`	View custom claim definitions
`claims:write`	Create/update custom claim definitions
`claims:delete`	Delete custom claim definitions
`claims:test`	Test custom claims without saving
`apps:read`	View app configurations
`apps:write`	Create/update app configurations
`apps:delete`	Delete apps
`flags:read`	View feature flags, environments, and overrides
`flags:write`	Create/update/delete feature flags, environments, and overrides
`feedback:read`	View feature requests and support tickets
`feedback:write`	Submit feature requests, votes, comments, and support tickets
`feedback:manage`	Triage feedback as staff: change status, reply, set priority
`vrt:read`	View visual regression runs and baselines
`vrt:write`	Submit visual regression runs and manage baselines
`release_notes:read`	View What’s New release notes
`release_notes:write`	Create, edit, publish, and delete What’s New release notes
`org:read`	View organization settings, usage, members, and notification preferences
`org:write`	Change organization settings, notification preferences, and the failure-rate alert
`alerts:read`	View risk alert rules and their deliveries
`alerts:write`	Create, update, and delete risk alert rules
`keys:read`	List API keys
`keys:write`	Create, rotate, and revoke API keys
`webhooks:read`	View webhook configurations
`webhooks:write`	Create/update webhooks
`webhooks:delete`	Delete webhooks
`webhooks:test`	Send test webhook events
`admin:audit`	Access audit logs
`admin:compliance`	Generate compliance reports
`admin:billing`	Access billing information
`admin:team`	Manage team members and invites
`attestation:validate`	Validate attestations
`api:all`	Full access to all APIs

Scope availability by tier

Tier	Available scopes
Free	None — no API keys
Pro	`analytics:read`, `devices:read`, `flags:read`, `flags:write`, `feedback:read`, `feedback:write`, `feedback:manage`, `vrt:read`, `vrt:write`, `release_notes:read`, `release_notes:write`, `org:read`, `org:write`, `alerts:read`, `keys:read`, `keys:write`
Business	Everything except `admin:*` and `api:all`
Enterprise	All scopes

Requesting a scope outside your tier returns 400 with the invalid scopes listed.

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Authentication

Key prefixes

List API keys

Create an API key

Rotate an API key

Revoke an API key

Scopes

See also

​Authentication

​Key prefixes

​List API keys

​Create an API key

​Rotate an API key

​Revoke an API key

​Scopes

​See also

Authentication

Key prefixes

List API keys

Create an API key

Rotate an API key

Revoke an API key

Scopes

See also