Skip to main content

​
Configuration

​
RevstackServerConfig

Configuration object for server-side API calls.
​
secretKey
string
required
Your project’s secret key from the Revstack dashboard. Keep this secure - never expose it to the client.
​
apiUrl
string
Custom API base URL (defaults to https://app.revstack.dev)
​
redirectTo
string
Optional redirect URL when requireEntitlement() denies access

​
Functions

​
getEntitlement

Checks if the current user has access to a feature. Must be called from a Server Component or Server Action. Signature 
async function getEntitlement(
  key: string,
  config: RevstackServerConfig
): Promise<Entitlement>
Parameters
  • key (string) - The feature key to check
  • config (RevstackServerConfig) - Server configuration with secretKey
Returns
  • Entitlement object with { key, hasAccess, value? }
How it works
  1. Extracts user identity from request headers (Authorization, X-Revstack-Auth, X-Revstack-Guest-Id)
  2. Authenticates to Revstack API using your secretKey
  3. Forwards user identity headers to resolve their entitlements
  4. Returns the entitlement for the specified key
Usage 
import { getEntitlement } from '@revstackhq/next/server';

const config = {
  secretKey: process.env.REVSTACK_SECRET_KEY!,
};

export default async function FeaturePage() {
  const entitlement = await getEntitlement('premium-feature', config);

  if (!entitlement.hasAccess) {
    return <div>Upgrade to access this feature</div>;
  }

  return <PremiumContent />;
}

​
requireEntitlement

Enforces entitlement access - redirects or throws an error if the user lacks access. Signature 
async function requireEntitlement(
  key: string,
  config: RevstackServerConfig
): Promise<Entitlement>
Parameters
  • key (string) - The required feature key
  • config (RevstackServerConfig) - Server configuration
Returns
  • Entitlement object if access is granted
Throws/Redirects
  • Redirects to config.redirectTo if provided and access is denied
  • Otherwise throws an error with message "Access denied: missing entitlement \"<key>\""
Usage 
import { requireEntitlement } from '@revstackhq/next/server';

const config = {
  secretKey: process.env.REVSTACK_SECRET_KEY!,
  redirectTo: '/pricing',
};

export default async function PremiumPage() {
  // Redirects to /pricing if user lacks access
  await requireEntitlement('premium-tier', config);

  return <PremiumDashboard />;
}

​
trackUsage

Reports metered usage (e.g., API calls, credits consumed) for the current user. Signature 
async function trackUsage(
  key: string,
  usage: UsageData,
  config: RevstackServerConfig
): Promise<void>
Parameters
  • key (string) - The feature key to track usage against
  • usage (UsageData) - Usage data (see below)
  • config (RevstackServerConfig) - Server configuration
UsageData
​
amount
number
For standard metered billing (e.g., 1 API call = 1 credit)
​
ai
object
For AI-specific billing based on token usage
Throws
  • Error if tracking fails (e.g., user has exhausted quota)
Usage 
import { trackUsage } from '@revstackhq/next/server';

const config = {
  secretKey: process.env.REVSTACK_SECRET_KEY!,
};

export async function POST(req: Request) {
  // Deduct 1 credit
  await trackUsage('api-calls', { amount: 1 }, config);

  const result = await processRequest(req);
  return Response.json(result);
}

​
withMetering

Higher-order function that wraps a Route Handler with fixed-cost metering. Signature 
function withMetering(
  key: string,
  amount: number,
  config: RevstackServerConfig,
  handler: RouteHandler
): RouteHandler
Parameters
  • key (string) - The feature key to meter
  • amount (number) - Fixed cost per request
  • config (RevstackServerConfig) - Server configuration
  • handler (RouteHandler) - Your route handler function
Returns
  • Wrapped route handler that:
    1. Deducts amount credits before invoking handler
    2. Returns 402 Payment Required if user lacks credits
    3. Invokes handler only if metering succeeds
Usage 
import { withMetering } from '@revstackhq/next/server';

const config = {
  secretKey: process.env.REVSTACK_SECRET_KEY!,
};

// Deduct 1 credit per request
export const POST = withMetering('ai-credits', 1, config, async (req) => {
  const body = await req.json();
  const result = await generateWithAI(body.prompt);
  return Response.json({ result });
});

​
Types

​
Entitlement

interface Entitlement {
  key: string;
  hasAccess: boolean;
  value?: string | number | boolean;
}

​
UsageData

interface UsageData {
  amount?: number;
  ai?: {
    modelId: string;
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
}

​
Identity Resolution

All server functions automatically extract user identity from request headers:
  • Authorization or X-Revstack-Auth - User’s JWT token
  • X-Revstack-Guest-Id - Guest fingerprint for anonymous users
You don’t need to manually pass these - the SDK handles it automatically in Server Components and Route Handlers.

Build docs developers (and LLMs) love

Get started for freeTalk to us