From 18d6cbd49f46f9b58b42f04492d63829f22367dd Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 11 Sep 2026 13:56:02 +0200 Subject: [PATCH 1/3] docs: explain synchronous entity creation and flag targeting --- api/api-access.md | 10 +++ api/reflag-rest-api/README.md | 80 +++++++++++++++------ api/reflag-rest-api/reflag-api-reference.md | 10 ++- 3 files changed, 74 insertions(+), 26 deletions(-) diff --git a/api/api-access.md b/api/api-access.md index 7cd4413..0621f3e 100644 --- a/api/api-access.md +++ b/api/api-access.md @@ -40,6 +40,16 @@ One primary use case is the [Reflag CLI](../sdk/documents/cli/), which can run i To start, create a new API key and select its scopes. After setting the necessary scopes, securely store the API key for use in your CI/CD pipelines or other automated processes. +For the [create a user and immediately enable a flag](reflag-rest-api/README.md#create-a-user-and-immediately-enable-a-flag) workflow, select both: + +| Scope | Purpose | +| --- | --- | +| `write:entities` | Create or update users and companies. This scope also permits entity deletion. | +| `write:flag:targeting` | Update flag targeting for users and companies. | + +`write:entities` does not grant flag targeting or company membership changes. Add +`read` separately if your integration also makes Management API GET requests. +

Create a new API key

After clicking _"Create,"_ you'll receive the API key. Remember to save it, as you won't be able to retrieve it later. diff --git a/api/reflag-rest-api/README.md b/api/reflag-rest-api/README.md index 8d7c87f..43ee00b 100644 --- a/api/reflag-rest-api/README.md +++ b/api/reflag-rest-api/README.md @@ -8,10 +8,10 @@ description: Introduction to Reflag Management API The Reflag Management API allows developers to programmatically interact with their Reflag accounts. -By using HTTP requests, such as GET, POST, PUT, and DELETE, users can perform actions like retrieving data, updating account settings, or managing resources without accessing the Reflag web application directly. This enables seamless integration with other systems, automation of tasks, and enhanced flexibility in account management. +Use it to create and update flags, manage users and companies, and grant flag access from your backend or back-office tools. For TypeScript applications, the [Management SDK](../../sdk/@reflag/management-sdk/README.md) provides typed methods for these operations. {% hint style="info" %} -The Reflag Management API serves a different purpose than the Runtime API. For app integrations, please use the [Runtime API](../public-api/). +Use the [Runtime API](../public-api/) and runtime SDKs to evaluate flags and track activity. Use the Management API to manage entities and change targeting. Application backends can use both, for example to create a user, grant flag access, and then evaluate that flag. {% endhint %} ## Authentication @@ -28,31 +28,65 @@ This section covers a few simple use cases for the Reflag Management API. The Management API enables customers to integrate their back-office systems with Reflag's flag targeting. By using our API, you can quickly provide access to specific flags for a company or user directly from your systems. -Here's a brief guide to enabling the `new-checkout-flow` flag for the `acme-corp` company: +Enable the existing `new-checkout-flow` flag for an existing `acme-corp` company with the Management SDK: ```typescript -await fetch( - `https://app.reflag.com/api/apps/${appId}/flags/specific-targets/${envId}`, - { - method: "PATCH", - headers: { - "Content-Type": "application/json", - "Authorization": `Bearer ${apiToken}`, - }, - body: JSON.stringify({ - updates: [ - { - flagKey: "new-checkout-flow", - value: true, - companyId: "acme-corp", - }, - ], - changeDescription: "Enabled new checkout flow for Acme Corp in prod", - }), - } -); +import { Api } from "@reflag/management-sdk"; + +const api = new Api({ accessToken: process.env.REFLAG_API_KEY }); + +await api.updateCompanyFlags({ + appId, + envId, + companyId: "acme-corp", + updates: [{ flagKey: "new-checkout-flow", specificTargetValue: true }], + changeDescription: "Enabled new checkout flow for Acme Corp in prod", +}); ``` +This uses `PATCH /apps/{appId}/envs/{envId}/companies/{companyId}/flags`. +For users, use `updateUserFlags` and the corresponding `/users/{userId}/flags` +endpoint. Set `specificTargetValue` to `null` to remove specific targeting; +other targeting rules may still enable the flag. + +### Create a user and immediately enable a flag + +Use a synchronous Management API upsert when a new user must be available to a +subsequent targeting request. Runtime tracking ingestion is asynchronous, so +sending a tracking event is not a substitute for awaiting this upsert. + +The flag must already exist. Your Management API key needs `write:entities` to +upsert the user and `write:flag:targeting` to enable the flag. See +[Management API Access](../api-access.md#management-api-access). + +```typescript +// `api` is the Management SDK client initialized above. +const scope = { appId, envId }; +const userId = "user-123"; + +await api.upsertUser({ ...scope, userId, name: "Jane Doe" }); + +const { flagStateVersion } = await api.updateUserFlags({ + ...scope, + userId, + updates: [{ flagKey: "new-checkout-flow", specificTargetValue: true }], +}); + +// Optional: evaluate immediately using an initialized Node SDK client +// configured for the same app and environment. +await client.refreshFlags(flagStateVersion); +const flag = client.getFlag("new-checkout-flow", { user: { id: userId } }); +``` + +Awaiting `upsertUser` makes the user available to the targeting request. Flag +configuration propagation to runtime SDKs is separate: `refreshFlags(flagStateVersion)` +requests the version containing the change or newer instead of waiting for the +next automatic refresh. If refreshing fails, the Node SDK retains cached or +fallback flags rather than throwing. + +The same workflow works for companies with `upsertCompany` and `updateCompanyFlags`. +For more detail, see [Waiting for flag changes to reach an SDK](../../sdk/@reflag/management-sdk/README.md#waiting-for-flag-changes-to-reach-an-sdk). + #### Automating TypeScript Type Generation with Reflag CLI in CI/CD To automate TypeScript type generation in your CI/CD pipeline, use the Reflag CLI. diff --git a/api/reflag-rest-api/reflag-api-reference.md b/api/reflag-rest-api/reflag-api-reference.md index 2be013d..a218cfe 100644 --- a/api/reflag-rest-api/reflag-api-reference.md +++ b/api/reflag-rest-api/reflag-api-reference.md @@ -54,14 +54,18 @@ description: >- [OpenAPI reflag-api](https://app.reflag.com/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="reflag-api" path="/apps/{appId}" method="get" %} +{% openapi-operation spec="reflag-api" path="/apps/{appId}/envs/{envId}/companies/{companyId}" method="put" %} [OpenAPI reflag-api](https://app.reflag.com/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="reflag-api" path="/apps" method="get" %} +{% openapi-operation spec="reflag-api" path="/apps/{appId}/envs/{envId}/companies/{companyId}" method="delete" %} [OpenAPI reflag-api](https://app.reflag.com/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="reflag-api" path="/apps/{appId}/flags" method="get" %} +{% openapi-operation spec="reflag-api" path="/apps/{appId}/envs/{envId}/users/{userId}" method="put" %} +[OpenAPI reflag-api](https://app.reflag.com/openapi.json) +{% endopenapi-operation %} + +{% openapi-operation spec="reflag-api" path="/apps/{appId}/envs/{envId}/users/{userId}" method="delete" %} [OpenAPI reflag-api](https://app.reflag.com/openapi.json) {% endopenapi-operation %} From 9075f48b4b638206a4ed98d5ee5f21117ae125e8 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 11 Sep 2026 14:00:01 +0200 Subject: [PATCH 2/3] docs: use direct HTTP examples for Management API workflows --- api/reflag-rest-api/README.md | 89 +++++++++++++++++++---------------- 1 file changed, 49 insertions(+), 40 deletions(-) diff --git a/api/reflag-rest-api/README.md b/api/reflag-rest-api/README.md index 43ee00b..5d89ce0 100644 --- a/api/reflag-rest-api/README.md +++ b/api/reflag-rest-api/README.md @@ -8,7 +8,7 @@ description: Introduction to Reflag Management API The Reflag Management API allows developers to programmatically interact with their Reflag accounts. -Use it to create and update flags, manage users and companies, and grant flag access from your backend or back-office tools. For TypeScript applications, the [Management SDK](../../sdk/@reflag/management-sdk/README.md) provides typed methods for these operations. +Use HTTP requests to create and update flags, manage users and companies, and grant flag access from your backend or back-office tools, in any language. {% hint style="info" %} Use the [Runtime API](../public-api/) and runtime SDKs to evaluate flags and track activity. Use the Management API to manage entities and change targeting. Application backends can use both, for example to create a user, grant flag access, and then evaluate that flag. @@ -28,25 +28,27 @@ This section covers a few simple use cases for the Reflag Management API. The Management API enables customers to integrate their back-office systems with Reflag's flag targeting. By using our API, you can quickly provide access to specific flags for a company or user directly from your systems. -Enable the existing `new-checkout-flow` flag for an existing `acme-corp` company with the Management SDK: +Enable the existing `new-checkout-flow` flag for an existing `acme-corp` company. +Set `APP_ID`, `ENV_ID`, and `REFLAG_API_KEY` to your app ID, environment ID, and +Management API key: -```typescript -import { Api } from "@reflag/management-sdk"; - -const api = new Api({ accessToken: process.env.REFLAG_API_KEY }); - -await api.updateCompanyFlags({ - appId, - envId, - companyId: "acme-corp", - updates: [{ flagKey: "new-checkout-flow", specificTargetValue: true }], - changeDescription: "Enabled new checkout flow for Acme Corp in prod", -}); +```sh +curl --fail-with-body \ + --request PATCH \ + "https://app.reflag.com/api/apps/${APP_ID}/envs/${ENV_ID}/companies/acme-corp/flags" \ + --header "Authorization: Bearer ${REFLAG_API_KEY}" \ + --header "Content-Type: application/json" \ + --data '{ + "updates": [ + { "flagKey": "new-checkout-flow", "specificTargetValue": true } + ], + "changeDescription": "Enabled new checkout flow for Acme Corp in prod" + }' ``` -This uses `PATCH /apps/{appId}/envs/{envId}/companies/{companyId}/flags`. -For users, use `updateUserFlags` and the corresponding `/users/{userId}/flags` -endpoint. Set `specificTargetValue` to `null` to remove specific targeting; +For users, send a PATCH request to +`/apps/{appId}/envs/{envId}/users/{userId}/flags` with the same body format. +Set `specificTargetValue` to `null` to remove specific targeting; other targeting rules may still enable the flag. ### Create a user and immediately enable a flag @@ -59,33 +61,40 @@ The flag must already exist. Your Management API key needs `write:entities` to upsert the user and `write:flag:targeting` to enable the flag. See [Management API Access](../api-access.md#management-api-access). -```typescript -// `api` is the Management SDK client initialized above. -const scope = { appId, envId }; -const userId = "user-123"; - -await api.upsertUser({ ...scope, userId, name: "Jane Doe" }); +First, send a PUT request to create or update the user. Once it succeeds, send a +PATCH request to enable the flag. The `&&` below runs the targeting request only +if the upsert succeeds: -const { flagStateVersion } = await api.updateUserFlags({ - ...scope, - userId, - updates: [{ flagKey: "new-checkout-flow", specificTargetValue: true }], -}); - -// Optional: evaluate immediately using an initialized Node SDK client -// configured for the same app and environment. -await client.refreshFlags(flagStateVersion); -const flag = client.getFlag("new-checkout-flow", { user: { id: userId } }); +```sh +curl --fail-with-body \ + --request PUT \ + "https://app.reflag.com/api/apps/${APP_ID}/envs/${ENV_ID}/users/user-123" \ + --header "Authorization: Bearer ${REFLAG_API_KEY}" \ + --header "Content-Type: application/json" \ + --data '{ "name": "Jane Doe" }' && +curl --fail-with-body \ + --request PATCH \ + "https://app.reflag.com/api/apps/${APP_ID}/envs/${ENV_ID}/users/user-123/flags" \ + --header "Authorization: Bearer ${REFLAG_API_KEY}" \ + --header "Content-Type: application/json" \ + --data '{ + "updates": [ + { "flagKey": "new-checkout-flow", "specificTargetValue": true } + ] + }' ``` -Awaiting `upsertUser` makes the user available to the targeting request. Flag -configuration propagation to runtime SDKs is separate: `refreshFlags(flagStateVersion)` -requests the version containing the change or newer instead of waiting for the -next automatic refresh. If refreshing fails, the Node SDK retains cached or -fallback flags rather than throwing. +A successful PUT response means the user is available to the targeting request; +no delay or polling is needed between these two calls. These are separate +operations: if the targeting request fails, the user remains created. + +Flag configuration propagation to runtime SDKs is separate. The PATCH response +includes `flagStateVersion`, the environment version containing the completed +targeting change. It does not mean every SDK has already received that version. -The same workflow works for companies with `upsertCompany` and `updateCompanyFlags`. -For more detail, see [Waiting for flag changes to reach an SDK](../../sdk/@reflag/management-sdk/README.md#waiting-for-flag-changes-to-reach-an-sdk). +For companies, use the same sequence with +`PUT /apps/{appId}/envs/{envId}/companies/{companyId}` followed by +`PATCH /apps/{appId}/envs/{envId}/companies/{companyId}/flags`. #### Automating TypeScript Type Generation with Reflag CLI in CI/CD From 788b758867344a5d43631d140e87d1f25b4cb085 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 11 Sep 2026 14:01:43 +0200 Subject: [PATCH 3/3] docs: keep workflow scopes in the Management API guide --- api/api-access.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/api/api-access.md b/api/api-access.md index 0621f3e..7cd4413 100644 --- a/api/api-access.md +++ b/api/api-access.md @@ -40,16 +40,6 @@ One primary use case is the [Reflag CLI](../sdk/documents/cli/), which can run i To start, create a new API key and select its scopes. After setting the necessary scopes, securely store the API key for use in your CI/CD pipelines or other automated processes. -For the [create a user and immediately enable a flag](reflag-rest-api/README.md#create-a-user-and-immediately-enable-a-flag) workflow, select both: - -| Scope | Purpose | -| --- | --- | -| `write:entities` | Create or update users and companies. This scope also permits entity deletion. | -| `write:flag:targeting` | Update flag targeting for users and companies. | - -`write:entities` does not grant flag targeting or company membership changes. Add -`read` separately if your integration also makes Management API GET requests. -

Create a new API key

After clicking _"Create,"_ you'll receive the API key. Remember to save it, as you won't be able to retrieve it later.