Feature and parameter access

Use feature and parameter access when your app needs to choose behavior before a billable action starts.

These checks are non-consuming. They answer questions such as:

• Can this customer use PDF export?
• Which invoice prefix should this workspace use?
• Should the app show an upgrade path before the user starts work?

If the action is costly or billable, still call Valqio before the work runs with an enforce or reservation helper. Feature and parameter access is the preview or routing step; usage enforcement is the transaction step.

Use a generated client

Generated clients expose feature helpers under flags and parameter helpers under configs. Console calls the product concept a parameter; the generated TypeScript surface uses configs because the runtime evaluates configured values.

import { createMyAppValqioClientFromEnv } from "./valqio.generated"

const myApp = createMyAppValqioClientFromEnv({
  runtimeOverrides: { mode: "remote-only" },
})

export async function getExportSettings({
  workspaceId,
  requestId,
}: {
  workspaceId: string
  requestId: string
}) {
  const customer = myApp.customer({ id: workspaceId }, { requestId })

  const pdfExport = await customer.flags.pdfExport.decision({
    fallback: false,
  })

  const invoicePrefix = await customer.configs.invoicePrefix.value({
    fallback: "INV",
  })

  return {
    allowed: pdfExport.allowed,
    reasonCode: pdfExport.reasonCode,
    invoicePrefix,
    requestId,
  }
}

Use the feature decision to shape the product response. Do not start the costly action just because a feature check allowed it.

const customer = myApp.customer({ id: workspaceId }, { requestId })

const pdfExport = await customer.flags.pdfExport.decision({
  fallback: false,
})

const invoicePrefix = await customer.configs.invoicePrefix.value({
  fallback: "INV",
})

if (!pdfExport.allowed) {
  return {
    status: 403,
    body: {
      reason: "upgrade_required",
      reasonCode: pdfExport.reasonCode,
      requestId,
    },
  }
}

const decision = await customer.meters.reportExports.enforce({
  quantity: 1,
  requestId,
  idempotencyKey: `report-export:${requestId}`,
})

if (!decision.allowed) {
  return {
    status: 402,
    body: {
      reasonCode: decision.reasonCode,
      requestId,
    },
  }
}

return exportReport({ invoicePrefix })

Use the runtime client directly

Use runtime.evaluate when you do not have a generated client yet or when you need to evaluate several access checks together.

import { createRuntimeClient } from "@valqio/sdk-node"

const runtime = createRuntimeClient({
  apiKey: process.env.VALQIO_API_KEY!,
  baseUrl: process.env.VALQIO_DATA_PLANE_URL!,
  projectId: process.env.VALQIO_PROJECT_ID!,
  environment: process.env.VALQIO_ENVIRONMENT!,
  mode: "remote-only",
})

const evaluation = await runtime.evaluate({
  requestId,
  subject: {
    type: "customer",
    key: workspaceId,
    projectId: process.env.VALQIO_PROJECT_ID!,
  },
  checks: [
    { key: "pdf-export", type: "flag" },
    { key: "invoice-prefix", type: "config" },
  ],
})

Keep this call on your backend. Browser code can call your own server route and receive product-specific fields such as allowed, reason, or invoicePrefix.

When to use this

Use feature and parameter access for:

• hiding or showing a product entry point
• returning a plan-aware denial before work starts
• choosing configured values such as limits, prefixes, templates, or model names
• previewing behavior before the app asks Valqio to consume usage

Do not use access checks as a substitute for usage enforcement. When work consumes credits, quota, reservations, or billable units, call Valqio again with the action, meter, quantity, request ID, and idempotency key.

Inspect evidence

Open Decisions → History in Console and search by request ID or subject. Confirm the access check happened before product work, then inspect the later enforce or reservation decision for the billable action.

For support handoffs, log:

• request ID
• subject type and key
• feature or parameter alias
• returned reason code
• later enforcement idempotency key when usage is consumed