License Keys

List license keys for a project
Returns every license key for a project with its current activation count. Plaintext keys are never included — only metadata and the hashed key's last-four characters (when populated).
GET https://api.appgram.dev/api/v1/license-keys
curl --request GET \
  --url https://api.appgram.dev/api/v1/license-keys \
  --header 'Authorization: Bearer <token>'

Mint a license key
Issue a new license key for a project. The response includes the plaintext key string ONCE — only its SHA-256 hash is persisted. Subsequent reads return metadata only, so the caller MUST capture `data.key` from this response. Optionally inline-upsert the end user by setting `end_user{external_id, email, name, plan, attributes}` instead of `end_user_id` — the EndUser is created or merged before the key is minted, and the key's `end_user_id` is set automatically. The `license_key_minted` webhook fires with `metadata.end_user_email` populated.
POST https://api.appgram.dev/api/v1/license-keys
curl --request POST \
  --url https://api.appgram.dev/api/v1/license-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "end_user": {
    "email": "string",
    "external_id": "string",
    "name": "string",
    "plan": "string"
  },
  "end_user_id": "string",
  "expires_at": "string",
  "max_devices": 0,
  "plan": "string",
  "project_id": "string"
}'

Get the project's public verification key
Returns the Ed25519 public key the host app embeds to verify entitlement JWTs locally. Auto-creates the keypair on the first call. The private signing key is never returned by this or any other endpoint.
GET https://api.appgram.dev/api/v1/license-keys/public-key
curl --request GET \
  --url https://api.appgram.dev/api/v1/license-keys/public-key \
  --header 'Authorization: Bearer <token>'

Rotate the project's signing keypair
Generate a fresh Ed25519 keypair for this project. Host apps embedding the old public key will fail JWT verification after their next refresh, so coordinate distributing the new public key BEFORE rotating. The new private key stays on the server.
POST https://api.appgram.dev/api/v1/license-keys/public-key/rotate
curl --request POST \
  --url https://api.appgram.dev/api/v1/license-keys/public-key/rotate \
  --header 'Authorization: Bearer <token>'

Get a license key by ID
Returns one license key with its hydrated end user (when assigned) and the full list of device activations. Plaintext key is never returned.
GET https://api.appgram.dev/api/v1/license-keys/{id}
curl --request GET \
  --url https://api.appgram.dev/api/v1/license-keys/{id} \
  --header 'Authorization: Bearer <token>'

Delete a license key
Permanently delete a license key and its activations. Prefer POST /revoke for normal lifecycle — delete is destructive and breaks audit trails.
DELETE https://api.appgram.dev/api/v1/license-keys/{id}
curl --request DELETE \
  --url https://api.appgram.dev/api/v1/license-keys/{id} \
  --header 'Authorization: Bearer <token>'

Update a license key
Partial update — only safe-to-change fields (end_user_id, plan, max_devices, expires_at, metadata) are accepted. Project, plaintext key, and status cannot be changed here; use the dedicated /revoke endpoint to retire a key.
PATCH https://api.appgram.dev/api/v1/license-keys/{id}
curl --request PATCH \
  --url https://api.appgram.dev/api/v1/license-keys/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "end_user_id": "string",
  "expires_at": "string",
  "max_devices": 0,
  "plan": "string"
}'

Revoke a license key
Mark a license key as revoked. Active host apps keep working until their currently-issued entitlement JWT expires (default 7 days); the next /portal/license-keys/refresh call will then fail.
POST https://api.appgram.dev/api/v1/license-keys/{id}/revoke
curl --request POST \
  --url https://api.appgram.dev/api/v1/license-keys/{id}/revoke \
  --header 'Authorization: Bearer <token>'

Activate a license key on a device
Public endpoint called by the customer's host app to bind a device fingerprint to one of the key's seats. Returns a signed entitlement JWT — store it locally and verify it on every launch with the embedded public key (no network call required after activation).
POST https://api.appgram.dev/portal/license-keys/activate
curl --request POST \
  --url https://api.appgram.dev/portal/license-keys/activate \
  --header 'Content-Type: application/json' \
  --data '{
  "device_fingerprint": "string",
  "device_name": "string",
  "key": "string",
  "platform": "string",
  "project_id": "string"
}'

Deactivate a device
Public endpoint called by the host app to release this device's seat against the license key. Idempotent — calling it for an already-deactivated device returns success. Use when the user uninstalls or wants to free a slot for a new machine.
POST https://api.appgram.dev/portal/license-keys/deactivate
curl --request POST \
  --url https://api.appgram.dev/portal/license-keys/deactivate \
  --header 'Content-Type: application/json' \
  --data '{
  "device_fingerprint": "string",
  "key": "string",
  "project_id": "string"
}'

Refresh an entitlement
Public endpoint called by the host app on a cadence (typically weekly, or when the JWT is near expiry) to re-issue the entitlement JWT. Server-side revocation takes effect on the next failed refresh — so a short refresh cadence is what makes /revoke bite quickly on customer devices.
POST https://api.appgram.dev/portal/license-keys/refresh
curl --request POST \
  --url https://api.appgram.dev/portal/license-keys/refresh \
  --header 'Content-Type: application/json' \
  --data '{
  "device_fingerprint": "string",
  "key": "string",
  "project_id": "string"
}'