API Licenze

Le API Licenze permettono di creare policy di licenza, emettere chiavi, validarle a runtime, gestire postazioni e dispositivi, e automatizzare l’emissione delle chiavi tramite webhook di pagamento. Supportano validazione online, fallback JWT offline e modalità ibride.

Due destinatari, due livelli di autenticazione:

Destinatario	Autenticazione	Endpoint
La tua app / SDK (runtime)	Nessun Bearer token necessario	`/validate`, `/activate`, `/deactivate`, `/usage`, `/revocation-list`
Admin / Console (gestione)	Bearer token + permesso	Tutti gli altri

Tutti gli endpoint richiedono l’header x-tenant.

Policy

Le policy definiscono cosa concede una licenza — funzionalità, postazioni, dispositivi, scadenza, formato chiave e modalità di validazione.

GET/api/licensing/policiesRequires: manage:license-policies

Elenca tutte le policy per il tenant corrente. Supporta paginazione e ricerca.

Parametri query

Parametro	Tipo	Descrizione
`page`	`number`	Numero di pagina (predefinito: 1)
`limit`	`number`	Elementi per pagina (predefinito: 20)
`search`	`string`	Filtra per nome o slug

Risposta di successo


{
  "success": true,
  "data": [
    {
      "id": "pol_abc123",
      "name": "Pro Plan",
      "slug": "pro-plan",
      "validationMode": "HYBRID",
      "isActive": true,
      "offlineGraceDays": 7,
      "revocationTtlMin": 60,
      "dimensions": {
        "seats": { "enabled": true, "defaultMax": 5 },
        "devices": { "enabled": true, "defaultMax": 3 },
        "expiry": { "enabled": true, "defaultDays": 365 },
        "features": { "enabled": true, "available": ["analytics", "export", "api-access"] },
        "keyFormat": {
          "prefix": "VIG",
          "segments": 4,
          "segmentLength": 4,
          "separator": "-",
          "charset": "BASE32"
        }
      },
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "pages": 1 }
}

POST/api/licensing/policiesRequires: manage:license-policies

Crea una nuova policy di licenza.

Corpo della richiesta


{
  "name": "Pro Plan",
  "slug": "pro-plan",
  "validationMode": "HYBRID",
  "dimensions": {
    "seats": { "enabled": true, "defaultMax": 5 },
    "devices": { "enabled": true, "defaultMax": 3 },
    "expiry": { "enabled": true, "defaultDays": 365 },
    "features": { "enabled": true, "available": ["analytics", "export"] },
    "keyFormat": {
      "prefix": "VIG",
      "segments": 4,
      "segmentLength": 4,
      "separator": "-",
      "charset": "BASE32"
    }
  }
}

Campo	Tipo	Obbligatorio	Descrizione
`name`	`string`	Sì	Nome visualizzato
`slug`	`string`	Sì	Slug univoco (es. `pro-plan`)
`validationMode`	`ONLINE \| HYBRID \| OFFLINE`	No	Predefinito: `HYBRID`
`dimensions`	`object`	No	Configurazione postazioni, dispositivi, funzionalità, scadenza, formato chiave
`offlineGraceDays`	`number`	No	Giorni di validità offline della chiave (predefinito: 7)
`revocationTtlMin`	`number`	No	Minuti prima della propagazione della revoca (predefinito: 60)

GET/api/licensing/policies/:idRequires: manage:license-policies

Ottieni una singola policy per ID.

PATCH/api/licensing/policies/:idRequires: manage:license-policies

Aggiorna una policy. Solo i campi forniti vengono modificati.

DELETE/api/licensing/policies/:idRequires: manage:license-policies

Elimina una policy. Fallisce se ci sono chiavi ancora emesse sotto di essa.

Chiavi

Le chiavi vengono emesse in base a una policy e assegnate a un licenziatario (utente, organizzazione o dispositivo).

GET/api/licensing/keysRequires: manage:license-keys

Elenca tutte le chiavi. Filtrabile per stato e policy.

Parametri query

Parametro	Tipo	Descrizione
`page`	`number`	Numero di pagina
`limit`	`number`	Elementi per pagina
`policyId`	`string`	Filtra per policy
`status`	`ACTIVE \| SUSPENDED \| REVOKED \| EXPIRED`	Filtra per stato

POST/api/licensing/keysRequires: manage:license-keys

Emetti una nuova chiave di licenza.

Corpo della richiesta


{
  "policyId": "pol_abc123",
  "licenseeType": "USER",
  "licenseeId": "user_xyz789",
  "notes": "Issued via Stripe checkout"
}

La risposta include l’oggetto chiave completo con key (la stringa di licenza) e jwtToken (per la validazione offline).

GET/api/licensing/keys/:idRequires: manage:license-keys

Ottieni una singola chiave per ID, inclusi policy, postazioni e dispositivi correlati.

POST/api/licensing/keys/:id/suspendRequires: manage:license-keys

Sospendi una chiave. Può essere riattivata successivamente.

POST/api/licensing/keys/:id/revokeRequires: manage:license-keys

Revoca permanentemente una chiave.

POST/api/licensing/keys/:id/reissueRequires: manage:license-keys

Riemetti una chiave con diritti aggiornati. La vecchia chiave viene revocata e ne viene generata una nuova.

Corpo opzionale


{
  "features": ["analytics", "export", "api-access"],
  "seatMax": 10,
  "deviceMax": 5,
  "expiresAt": "2027-03-15T00:00:00Z"
}

Postazioni

GET/api/licensing/keys/:id/seatsRequires: manage:license-keys

Elenca tutte le postazioni (utenti assegnati) per una chiave.

POST/api/licensing/keys/:id/seatsRequires: manage:license-keys

Assegna una postazione a un utente. Fallisce se il limite di postazioni è stato raggiunto.


{ "userId": "user_abc" }

DELETE/api/licensing/keys/:id/seats/:userIdRequires: manage:license-keys

Rilascia la postazione di un utente.

Dispositivi

GET/api/licensing/keys/:id/devicesRequires: manage:license-keys

Elenca tutti i dispositivi attivati per una chiave.

DELETE/api/licensing/keys/:id/devices/:deviceIdRequires: manage:license-keys

Rimuovi un dispositivo da una chiave.

Validazione (Pubblica)

Questi endpoint vengono chiamati dalla tua applicazione a runtime. Non è richiesto alcun Bearer token.

POST/api/licensing/validate

Valida una chiave di licenza online. Restituisce validità, funzionalità, conteggio postazioni/dispositivi e scadenza.

Corpo della richiesta


{ "key": "VIG-A8BC-D3EF-G4HJ-K5LM" }

Risposta di successo


{
  "valid": true,
  "features": ["analytics", "export"],
  "seats": { "used": 2, "max": 5 },
  "devices": { "used": 1, "max": 3 },
  "expiresAt": "2027-01-15T00:00:00Z"
}

Risposta chiave non valida


{
  "valid": false,
  "reason": "REVOKED"
}

Possibili valori di reason: INVALID, EXPIRED, REVOKED, SUSPENDED, SEAT_LIMIT, DEVICE_LIMIT.

Attivazione Dispositivo (Pubblica)

POST/api/licensing/activate

Registra un dispositivo associato a una chiave di licenza. Utilizzalo al primo avvio di un’app desktop/mobile.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6",
  "name": "John's MacBook Pro"
}

Restituisce 200 in caso di successo. Restituisce 409 se il limite di dispositivi è stato raggiunto.

POST/api/licensing/deactivate

Rimuovi un dispositivo da una chiave. Utilizzalo quando l’utente esce o disinstalla.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6"
}

Tracciamento Utilizzo (Pubblico)

POST/api/licensing/usage

Registra una metrica di utilizzo per una chiave. Utile per licenze a consumo/metriche.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "metric": "api_calls",
  "amount": 1
}

GET/api/licensing/usage/:key

Ottieni i dati di utilizzo correnti per una chiave su tutte le metriche.

Lista di Revoca (Pubblica)

GET/api/licensing/revocation-list

Restituisce un JWT firmato contenente tutti i JTI delle chiavi revocate. Utilizzato dall’SDK per il controllo della revoca offline.

La risposta è application/jwt con Cache-Control: public, max-age=3600. L’SDK lo recupera automaticamente.

Regole di Automazione

Le regole di automazione collegano eventi di pagamento (Stripe, PayPal) ad azioni sulle licenze (emissione, attivazione, sospensione, revoca).

GET/api/licensing/automationRequires: manage:license-policies

Elenca tutte le regole di automazione.

POST/api/licensing/automationRequires: manage:license-policies

Crea una nuova regola di automazione.


{
  "name": "Stripe checkout → issue key",
  "provider": "stripe",
  "triggerEvent": "checkout.session.completed",
  "action": "issue_key",
  "policyId": "pol_abc123",
  "isActive": true
}

Provider	Eventi Trigger
`stripe`	`checkout.session.completed`, `invoice.paid`, `payment_intent.succeeded`
`paypal`	`PAYMENT.CAPTURE.COMPLETED`
`manual`	`manual_trigger`

Azione	Descrizione
`issue_key`	Emette una nuova chiave sotto la policy collegata
`activate_key`	Attiva una chiave esistente
`suspend_key`	Sospende una chiave
`revoke_key`	Revoca una chiave

GET/api/licensing/automation/:idRequires: manage:license-policies

Ottieni una singola regola di automazione.

PATCH/api/licensing/automation/:idRequires: manage:license-policies

Aggiorna una regola di automazione.

DELETE/api/licensing/automation/:idRequires: manage:license-policies

Elimina una regola di automazione.

Webhook

Questi endpoint ricevono eventi dai provider di pagamento. Vengono verificati tramite firma e non richiedono Bearer token.

POST/api/licensing/webhooks/stripe

Riceve eventi webhook Stripe. Verificato tramite header stripe-signature. Imposta STRIPE_LICENSING_WEBHOOK_SECRET nel tuo ambiente.

POST/api/licensing/webhooks/paypal

Riceve eventi webhook PayPal. Verificato tramite HMAC-SHA256. Imposta PAYPAL_LICENSING_WEBHOOK_SECRET e PAYPAL_LICENSING_WEBHOOK_ID nel tuo ambiente.

Statistiche

GET/api/licensing/statsRequires: view:license-stats

Restituisce statistiche aggregate sulle licenze.


{
  "success": true,
  "data": {
    "totalPolicies": 3,
    "totalKeys": 142,
    "activeKeys": 98,
    "revokedKeys": 12,
    "suspendedKeys": 5,
    "expiredKeys": 27,
    "policyDistribution": [
      { "policyId": "pol_abc", "policyName": "Pro Plan", "count": 80 }
    ],
    "recentKeys": []
  }
}