Apps

Applications are the top-level container for your licensing. Each app has its own RSA key pair, tiers, features, customers, and licenses.

Overview

When you create an application, Blackwalnut automatically generates a 4096-bit RSA key pair:

  • Private key - Used to sign license tokens. Encrypted at rest with AES-256-GCM.
  • Public key - Used to verify license tokens. Can be distributed to your software.

App Properties

Field Type Description
name string Display name for the application
slug string URL-safe identifier. Used in API routes and JWT audience claim.
description string? Optional description
webhook_url string? URL for webhook notifications (license events)
public_key_pem string PEM-formatted RSA public key

Slug Format

App slugs must follow these rules:

  • Lowercase letters, numbers, and hyphens only
  • Maximum 63 characters
  • Must be unique across your account

Valid: my-app, app-123, myapp

Invalid: My_App, my app, my.app

Creating an App

POST /api/v1/apps 
$ curl -X POST http://localhost:4000/api/v1/apps \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Desktop App",
    "slug": "desktop-app",
    "description": "License management for my desktop application"
  }'

The response includes the auto-generated public key in PEM format. The private key is stored encrypted and never exposed through the API.

Key Rotation

If you need to rotate your RSA keys (e.g., suspected compromise), use the key rotation endpoint. This will:

  1. Generate a new 4096-bit RSA key pair
  2. Replace the existing keys
  3. Re-sign all active (non-expired, non-revoked) licenses with the new key
POST /api/v1/apps/:slug/rotate-keys 
$ curl -X POST http://localhost:4000/api/v1/apps/desktop-app/rotate-keys \
  -H "Authorization: Bearer sk_live_..."

# Response
{
  "data": {
    "message": "Keys rotated successfully",
    "licenses_resigned": 42,
    "public_key_pem": "-----BEGIN PUBLIC KEY-----\n..."
  }
}

Important: After rotating keys, you must distribute the new public key to your software. Existing tokens signed with the old key will fail verification.

Public Key Distribution

Your software needs the public key to verify licenses offline. You can:

  • Bundle the key in your application binary
  • Fetch it at runtime from the public API (no auth required)
GET /api/v1/apps/:slug/public-key 
# No authentication required
$ curl http://localhost:4000/api/v1/apps/desktop-app/public-key

# Returns raw PEM (Content-Type: application/x-pem-file)
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----
Quick Start Tiers & Features