--- title: flags description: The `flags` package provides the core functionality for integrating with Vercel. --- # flags ### `verifyAccess` A method for verifying access to your flags endpoint based on encrypted tokens (JWEs) generated by the SDK functions documented below. You can use `verifyAccess` to keep your endpoint private, but allow the Vercel Toolbar to access it. Returns a `Promise` with a `true` or `false` value. If you are using Next.js App Router you should use [`createFlagsDiscoveryEndpoint`](/api-reference/frameworks/next#createflagsdiscoveryendpoint) instead, which will create the full route handler. | Parameter | Type | Description | | --------------- | -------- | ----------------------------- | | `authorization` | `string` | Authorization token to verify | ```tsx title="app/.well-known/vercel/flags/route.ts#next" import { NextResponse, type NextRequest } from "next/server"; import { verifyAccess, version, type ProviderData, type ApiData } from "flags"; export async function GET(request: NextRequest) { const access = await verifyAccess(request.headers.get('Authorization')); if (!access) return NextResponse.json(null, { status: 401 }); const providerData: ProviderData = /* ... */ return NextResponse.json(providerData, { headers: { 'x-flags-sdk-version': version }, }); } ``` If you are using the `Pages` router, you will need to add the following to your `next.config.js`. This is because the `Pages` router can't specify API routes outside of the `api` folder. This means you need a [rewrite](https://nextjs.org/docs/pages/api-reference/next-config-js/rewrites). ```tsx title="pages/api/vercel/flags.ts#next" import type { NextApiRequest, NextApiResponse } from "next"; import { type ProviderData, verifyAccess } from "flags"; export async function handler(request: NextApiRequest, response: NextApiResponse) { const access = await verifyAccess(request.headers.get('Authorization')); if (!access) return response.json(null, { status: 401 }); const providerData: ProviderData = { ... }; return response.status(200).json(providerData); } ``` ```tsx title="next.config.js" module.exports = { async rewrites() { return [ { source: '/.well-known/vercel/flags', destination: '/api/vercel/flags', }, ]; }, }; ``` ### `mergeProviderData` Merges provider data from multiple sources. Extends the feature flags defined in code with metadata from your feature flag provider, for use with the Flags Explorer. | Parameter | Type | Description | | --------- | ------------------------------------------- | ----------------------------------------- | | `data` | `(ProviderData \| Promise)[]` | A list of provider data objects to merge. | ```ts title="app/.well-known/vercel/flags/route.ts#next" import { getProviderData, createFlagsDiscoveryEndpoint } from 'flags/next'; import { getProviderData as getStatsigProviderData } from '@flags-sdk/statsig'; import { mergeProviderData } from 'flags'; import * as flags from '../../../../flags'; export const GET = createFlagsDiscoveryEndpoint(async (request) => { return mergeProviderData([ getProviderData(flags), getStatsigProviderData({ consoleApiKey: process.env.STATSIG_CONSOLE_API_KEY, projectId: process.env.STATSIG_PROJECT_ID, }), ]); }); ``` ### `reportValue` Reports the value of a feature flag to Vercel so it can show up in Runtime Logs and be used with Web Analytics custom server-side events. Returns `undefined`. | Parameter | Type | Description | | --------- | -------- | ------------------------- | | `key` | `string` | Key of the feature flag | | `value` | `any` | Value of the feature flag | ```js import { reportValue } from 'flags'; reportValue('summer-sale', true); ``` ### Encryption and Decryption Functions The flags package provides multiple purpose-specific encryption and decryption functions for different types of flag data. These functions add purpose claims to prevent misuse between different data types. #### `encryptFlagValues` Encrypts flag values data with a purpose claim. Returns a `Promise`. | Parameter | Type | Description | | --------------------------- | -------------------------- | ------------------------------------------------------------------------ | | `flagValues` | `FlagValuesType` | Flag values to be encrypted | | `secret` (Optional) | `string` | The secret being used to encrypt. Defaults to `process.env.FLAGS_SECRET` | | `expirationTime` (Optional) | `string \| number \| Date` | When the encrypted data should expire. Defaults to '1y' (1 year) | ```tsx title="app/page.tsx" import { encryptFlagValues, type FlagValuesType } from 'flags'; import { FlagValues } from 'flags/react'; async function ConfidentialFlagValues({ values }: { values: FlagValuesType }) { const encryptedFlagValues = await encryptFlagValues(values); return ; } export function Page() { const values = { exampleFlag: true }; return (
{/* Some other content */}
); } ``` #### `decryptFlagValues` Decrypts flag values data, ensuring the proper purpose claim. Returns a `Promise`. | Parameter | Type | Description | | ------------------- | -------- | ----------------------------------------------------------------------------- | | `encryptedData` | `string` | Encrypted flag values to be decrypted | | `secret` (Optional) | `string` | The secret being used to decrypt data. Defaults to `process.env.FLAGS_SECRET` | #### `encryptFlagDefinitions` Encrypts flag definitions data with a purpose claim. Returns a `Promise`. | Parameter | Type | Description | | --------------------------- | -------------------------- | ------------------------------------------------------------------------ | | `flagDefinitions` | `FlagDefinitionsType` | Flag definitions to be encrypted | | `secret` (Optional) | `string` | The secret being used to encrypt. Defaults to `process.env.FLAGS_SECRET` | | `expirationTime` (Optional) | `string \| number \| Date` | When the encrypted data should expire. Defaults to '1y' (1 year) | #### `decryptFlagDefinitions` Decrypts flag definitions data, ensuring the proper purpose claim. Returns a `Promise`. | Parameter | Type | Description | | ------------------- | -------- | ----------------------------------------------------------------------------- | | `encryptedData` | `string` | Encrypted flag definitions to be decrypted | | `secret` (Optional) | `string` | The secret being used to decrypt data. Defaults to `process.env.FLAGS_SECRET` | #### `encryptOverrides` Encrypts flag overrides data with a purpose claim. Returns a `Promise`. | Parameter | Type | Description | | --------------------------- | -------------------------- | ------------------------------------------------------------------------ | | `overrides` | `FlagOverridesType` | Flag overrides to be encrypted | | `secret` (Optional) | `string` | The secret being used to encrypt. Defaults to `process.env.FLAGS_SECRET` | | `expirationTime` (Optional) | `string \| number \| Date` | When the encrypted data should expire. Defaults to '1y' (1 year) | #### `decryptOverrides` Decrypts flag overrides data, ensuring the proper purpose claim. Returns a `Promise`. | Parameter | Type | Description | | ------------------- | -------- | ----------------------------------------------------------------------------- | | `encryptedData` | `string` | Encrypted flag overrides to be decrypted | | `secret` (Optional) | `string` | The secret being used to decrypt data. Defaults to `process.env.FLAGS_SECRET` | The primary use case for `decryptOverrides` is decrypting data stored inside the `vercel-flag-overrides` cookie. ```tsx title="app/get-flags.ts#next" import { FlagOverridesType, decryptOverrides } from 'flags'; import { type NextRequest } from 'next/server'; import { cookies } from 'next/headers'; async function getFlags(request: NextRequest) { const overrideCookie = cookies().get('vercel-flag-overrides')?.value; const overrides = overrideCookie ? await decryptOverrides(overrideCookie) : {}; const flags = { exampleFlag: overrides?.exampleFlag ?? false, }; return flags; } ``` #### `verifyAccessProof` Compared to `verifyAccess` which is used commonly to keep your endpoint private, `verifyAccessProof` may rarely be needed for advanced use cases. Verifies that an access proof token is valid. Returns a `Promise` with a `true` or `false` value. | Parameter | Type | Description | | ------------------- | -------- | ---------------------------------------------------------------------- | | `encryptedData` | `string` | Encrypted access proof token to verify | | `secret` (Optional) | `string` | The secret used for decryption. Defaults to `process.env.FLAGS_SECRET` | ```tsx title="app/verify-access-proof.ts" import { verifyAccessProof } from 'flags'; // Example of verifying an access proof token const isValid = await verifyAccessProof(tokenFromRequest); if (isValid) { // Handle valid token } ``` ### `safeJsonStringify` A safe version of `JSON.stringify` that escapes the resulting output to prevent XSS attacks. Returns `string`. | Parameter | Type | Description | | --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `value` | `any` | A valid JSON object to convert | | `replacer` (Optional) | `function` \| `Array` | A replacer [function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#using_a_function_as_replacer) or [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#using_an_array_as_replacer) | | `space` (Optional) | `string` \| `number` | Specifies the spacing in the output | ```js import { safeJsonStringify } from 'flags'; safeJsonStringify({ markup: '' }); // '{"markup":"\\u003chtml>\\u003c/html>"}' ```