check()

Check if a customer has access to a specific feature or entitlement. Use this for access control and gating.

Signature

await owo.check({
  customer: string,    // Your internal user ID
  feature: string,     // Feature key to check
  value?: number,      // Units to check against limit (default: 1)
  entity?: string,     // Optional entity scope (seat, workspace, org)
  sendEvent?: boolean, // Atomically track if allowed
  customerData?: {     // Optional: auto-create customer
    email: string,
    name?: string,
    metadata?: Record<string, unknown>,
  },
}): Promise<CheckResult>

Parameters

Parameter	Type	Required	Description
`customer`	`string`	✅	Your internal user ID
`feature`	`string`	✅	Feature key to check access for
`value`	`number`	-	Units to check against limit
`entity`	`string`	-	Scope to an entity (must exist)
`sendEvent`	`boolean`	-	Atomically track if allowed
`customerData`	`object`	-	Auto-create customer if missing

When using entity, the entity must be created with addEntity() first. Checking a non-existent entity returns entity_not_found error.

Response

interface CheckResult {
  allowed: boolean;
  code: string; // access_granted, limit_exceeded, overage_allowed, etc.
  usage: number | null;
  limit: number | null;
  balance: number | null;
  resetsAt: string | null;
  resetInterval: string | null;
  details: {
    message: string;
    planName?: string;
    trial?: boolean;
    trialEndsAt?: string | null;
  };
}

Examples

Basic Access Check

import { Owostack } from "@owostack/core";

const owo = new Owostack({ secretKey: process.env.OWOSTACK_API_KEY });

// Check if user can access premium features
const result = await owo.check({
  customer: "user_123",
  feature: "premium_features",
});

if (result.allowed) {
  // Grant access
  showPremiumContent();
} else {
  // Prompt upgrade
  showUpgradeModal();
}

Metered Features

// Check API call quota
const result = await owo.check({
  customer: "user_123",
  feature: "api_calls",
});

if (!result.allowed) {
  console.log("Quota exceeded", result.balance, result.resetsAt);
}

// Process the request...

Multiple Feature Checks

// Check multiple features in parallel
const [canExport, canAnalyze, canShare] = await Promise.all([
  owo.check({ customer: "user_123", feature: "export" }),
  owo.check({ customer: "user_123", feature: "analytics" }),
  owo.check({ customer: "user_123", feature: "team_sharing" }),
]);

console.log({
  export: canExport.allowed,
  analytics: canAnalyze.allowed,
  sharing: canShare.allowed,
});

Best Practices

Cache results - For high-traffic endpoints, cache check results for a few seconds
Fail open or closed - Decide your failure mode if the API is unreachable
Check early - Validate access at the start of expensive operations
Use middleware - Create reusable middleware for common access patterns

check()

On this page