Licensing API Reference¶

REST API endpoints for license and subscription management.

Endpoints Overview¶

Integration API (JWT Auth)¶

These endpoints are for application integrations and require JWT authentication:

Admin API (M2M Auth)¶

These endpoints require Super Admin or M2M authentication:

SDK vs Raw API¶

import { createAuthVital } from '@authvital/sdk/server';

const authvital = createAuthVital({ /* config */ });

// Check license
const result = await authvital.licenses.check(req, undefined, 'app-123');

if (result.hasLicense) {
  console.log('License type:', result.licenseType);
}

// Check feature
const { hasFeature } = await authvital.licenses.hasFeature(
  req, undefined, 'app-123', 'sso'
);

# Check license
curl -H "Authorization: Bearer $JWT" \
  "https://auth.example.com/api/integration/licenses/check?applicationId=app-123"

# Check feature
curl -H "Authorization: Bearer $JWT" \
  "https://auth.example.com/api/integration/licenses/feature?applicationId=app-123&featureKey=sso"

Check License¶

GET /api/integration/licenses/check¶

Check if the authenticated user (or specified user) has a license for an application.

Query Parameters:

Response (200 OK) - Has License:

{
  "hasLicense": true,
  "licenseType": "pro",
  "licenseTypeName": "Pro Plan",
  "features": ["api-access", "advanced-reports", "sso"],
  "assignedAt": "2024-01-15T10:30:00Z"
}

Response (200 OK) - No License:

{
  "hasLicense": false,
  "licenseType": null,
  "licenseTypeName": null,
  "features": []
}

Check Feature¶

GET /api/integration/licenses/feature¶

Check if a user has access to a specific license feature.

Query Parameters:

Response (200 OK):

{
  "hasFeature": true
}

Get License Type¶

GET /api/integration/licenses/type¶

Get the license type slug for a user.

Query Parameters:

Response (200 OK):

{
  "licenseType": "pro"
}

List Licensed Users¶

GET /api/integration/licenses/apps/:applicationId/users¶

Get all users with licenses for an application in the authenticated tenant.

Response (200 OK):

[
  {
    "userId": "user-123",
    "email": "user@example.com",
    "givenName": "John",
    "familyName": "Doe",
    "licenseType": "pro",
    "licenseTypeName": "Pro Plan",
    "assignedAt": "2024-01-15T10:30:00Z"
  }
]

Count Licensed Users¶

GET /api/integration/licenses/apps/:applicationId/count¶

Get count of licensed users for an application.

Response (200 OK):

{
  "count": 42
}

Grant License¶

POST /api/integration/licenses/grant¶

Assign a license to a user.

Request:

{
  "userId": "user-123",
  "applicationId": "app-456",
  "licenseTypeId": "license-pro"
}

Response (201 Created):

{
  "id": "assignment-789",
  "userId": "user-123",
  "licenseTypeId": "license-pro",
  "licenseTypeName": "Pro Plan",
  "assignedAt": "2024-01-15T10:30:00Z"
}

SDK Equivalent:

await authvital.licenses.grant(req, {
  userId: 'user-123',
  applicationId: 'app-456',
  licenseTypeId: 'license-pro',
});

Revoke License¶

POST /api/integration/licenses/revoke¶

Remove a license from a user.

Request:

{
  "userId": "user-123",
  "applicationId": "app-456"
}

Response (200 OK):

{
  "success": true,
  "message": "License revoked"
}

SDK Equivalent:

await authvital.licenses.revoke(req, {
  userId: 'user-123',
  applicationId: 'app-456',
});

Admin: Tenant License Overview¶

GET /api/licensing/tenants/:tenantId/license-overview¶

Get full license overview for a tenant. Requires Super Admin or M2M auth.

Response (200 OK):

{
  "tenantId": "tenant-123",
  "tenantName": "Acme Corporation",
  "totalSeatsOwned": 50,
  "totalSeatsAssigned": 35,
  "totalSeatsAvailable": 15,
  "subscriptions": [
    {
      "applicationId": "app-456",
      "applicationName": "Project Manager",
      "licenseTypeId": "license-pro",
      "licenseTypeName": "Pro Plan",
      "quantityPurchased": 50,
      "quantityAssigned": 35,
      "quantityAvailable": 15,
      "status": "ACTIVE"
    }
  ]
}

SDK Equivalent:

const overview = await authvital.licenses.getTenantOverview('tenant-123');

Error Responses¶