License Validation API

Validate whether a user has a valid license and get license details.

Endpoint

POST /api/v1/validate

This is the core endpoint of the Slice API. It validates a user's license status and returns the license details if valid. This endpoint is called from your application to check if a user has access to licensed features.

Authentication

Requires API key authentication via Bearer token in the Authorization header.

Request

Headers

Authorization: Bearer sk_live_abc123...
Content-Type: application/json

Request Body

{
  "userId": "user_123"  // Required: Your internal user identifier
}

Parameters

userId (string, required)

Your internal user identifier. This can be any string that uniquely identifies the user in your system (e.g., user ID, email, username).

Response: Valid License

HTTP 200 - License is valid

{
  "success": true,
  "data": {
    "valid": true,
    "license": {
      "id": "license_abc123",
      "productId": "product_xyz",
      "planId": "plan_456",
      "status": "active",
      "maxSeats": 5,
      "expiresAt": null,
      "features": ["feature1", "feature2"],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    "activation": {
      "id": "activation_789",
      "userId": "user_internal_id",
      "licenseId": "license_abc123",
      "activatedAt": "2024-01-01T00:00:00Z",
      "lastCheckedAt": "2024-01-15T12:00:00Z"
    },
    "features": ["feature1", "feature2"]
  }
}

Response Fields

  • valid - true when license is valid
  • license - The license object with all details
  • activation - Activation record (created/updated on validation)
  • features - Array of feature flags from the license

Response: Invalid License

HTTP 200 - License is invalid (this is not an error)

{
  "success": true,
  "data": {
    "valid": false,
    "reason": "no_license"
  }
}

Invalid Reasons

  • no_license - User has no assigned license
  • expired - License has expired
  • revoked - License has been revoked
  • suspended - License is suspended
  • exceeded_seats - License has reached its seat limit
  • user_not_found - User does not exist (rare, user is auto-created)

Note: An invalid license response is not an error. The API returns HTTP 200 with valid: false. This allows you to handle invalid licenses gracefully in your application.

How It Works

What happens when you validate a license

  1. The API looks up the user by their userId (auto-creates if doesn't exist)
  2. Retrieves all licenses assigned to that user
  3. Finds the first active, non-expired license
  4. Checks seat limits if the license has maxSeats set
  5. Creates or updates the activation record
  6. Returns the license details and features

Auto-creation: If a user doesn't exist, the API automatically creates them with the provided userId. This simplifies integration - you don't need to create users before validating.

Code Examples

cURL

curl -X POST https://api.slice.example.com/api/v1/validate \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123"}'

JavaScript/Node.js

const response = await fetch('https://api.slice.example.com/api/v1/validate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SLICE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 'user_123' }),
});

const result = await response.json();

if (result.data.valid) {
  console.log('License valid:', result.data.license);
  console.log('Features:', result.data.features);
} else {
  console.log('License invalid:', result.data.reason);
}

Using the SDK (Recommended)

import { SliceClient } from '@sliceapi/sdk';

const client = new SliceClient(process.env.SLICE_API_KEY!);

const result = await client.validate.validate('user_123');

if (result.valid) {
  console.log('License valid:', result.license);
  console.log('Features:', result.features);
} else {
  console.log('License invalid:', result.reason);
}

Error Responses

400 Bad Request

Missing or invalid request parameters

{
  "success": false,
  "error": "Missing required field: userId"
}

401 Unauthorized

Invalid or missing API key

{
  "success": false,
  "error": "Unauthorized"
}

429 Too Many Requests

Rate limit exceeded

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later.",
  "retryAfter": 60
}

Best Practices

  • Validate licenses at application startup or when accessing premium features
  • Cache validation results to reduce API calls (respect license expiration)
  • Handle all invalid reasons appropriately (show upgrade prompts, etc.)
  • Use the SDK for type safety and automatic error handling
  • Monitor rate limits and implement exponential backoff
  • Log validation failures for debugging and analytics