# Overview

Feature Entitlements in AccessIQ serve two purposes:

1. **Feature Flags** -- control which features are enabled or disabled in your applications, with targeting rules and progressive rollouts.
2. **JWT Entitlements** -- embed feature entitlements directly in the user's access token so your application can check permissions without additional API calls.

## Key Concepts

| Concept               | Description                                                                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project               | A container for organizing flags (e.g., one project per product). Each project has a name, key, description, and color for visual identification.                                            |
| Environment           | A deployment target within a project (e.g., Development, Staging, Production). Each environment has its own flag states, so a flag can be enabled in Development but disabled in Production. |
| Flag                  | A named feature toggle with a value that can differ per environment. Flags can be Boolean (on/off), String, Number, or JSON type.                                                            |
| Targeting rule        | Logic that determines which users or groups receive a specific flag value, based on attributes like user ID, email, organization, role, plan, country, or platform.                          |
| Rollout               | A gradual release of a flag value to an increasing percentage of users over a configured duration.                                                                                           |
| SDK key               | A credential used by your application to connect to the feature flag service. Keys come in three types: Server, Client, and Mobile.                                                          |
| Organization override | A flag value that applies only to users within a specific organization, overriding the default environment value.                                                                            |

## How Feature Flags Work

1. Create a flag in a project (e.g., `new-dashboard`).
2. Set its value per environment -- enabled in Development, disabled in Production.
3. Optionally add targeting rules to enable it for specific users, organizations, or attributes.
4. Your application checks the flag value using the AccessIQ SDK or API.

## How JWT Entitlements Work

When a user signs in, AccessIQ can include their feature entitlements in the access token. Your application reads these entitlements directly from the JWT, which means:

* No additional network request to check feature access
* Entitlements are evaluated at token issuance and refreshed on token renewal
* Suitable for features that do not change within a session

To enable JWT entitlements for a flag, toggle **Include in JWT** when creating or editing the flag.

## Admin Workflows

### Creating a Project

Projects are the top-level container for organizing your feature flags. You might create one project per product, team, or business line.

1. Go to **Feature Entitlements > Projects**.
2. Click **Create Project**.
3. Enter a **Name** for the project (e.g., "Web App" or "Mobile Platform").
4. Enter a **Key** -- a unique identifier used in API calls. The key is auto-generated from the name but can be customized.
5. Add a **Description** to help your team understand the project's purpose.
6. Choose a **Color** from the palette to visually distinguish this project in lists and cards.
7. Click **Create**.

You can switch between a grid view and a list view on the Projects page. Each project card shows the number of flags, environments, and SDK keys it contains.

### Setting Up Environments

Each project needs at least one environment to manage flag states. Common setups include Development, Staging, and Production.

1. Go to **Feature Entitlements > Environments**.
2. Select the project from the dropdown.
3. Click **Create Environment**.
4. Enter a **Name** (e.g., "Production"), a **Key** (e.g., `production`), and optionally a **Color**.
5. Click **Create**.

You can also manage environments from within a project's detail page by navigating to **Feature Entitlements > Projects** and clicking into a specific project.

### Creating Feature Flags

1. Go to **Feature Entitlements > Feature Flags**.
2. Select the project that should contain the flag.
3. Click **Create Flag**.
4. Enter a **Name** (e.g., "New Dashboard") and a **Key** (e.g., `new-dashboard`). The key is auto-generated from the name but can be customized.
5. Add a **Description** explaining what the flag controls.
6. Select a **Flag Type**: Boolean, String, Number, or JSON.
7. Optionally add **Tags** to categorize the flag for easier filtering.
8. Click **Create**.

After creation, the flag appears in the flag list with toggle switches for each environment. Click a toggle to enable or disable the flag in that environment.

You can filter flags by searching, by tag, or by toggling the **Show Archived** option to view retired flags. Flags can be displayed in a card view or table view.

### Setting Flag Values Per Environment

For Boolean flags, use the toggle switch next to each environment name to turn the flag on or off.

For String, Number, and JSON flags, click the flag to open its detail panel, then set the value for each environment individually.

Each flag state is independent per environment, so you can safely test a feature in Development while keeping it disabled in Production.

### Adding Targeting Rules

Targeting rules let you control which users see a particular flag value, even within the same environment.

1. Go to **Feature Entitlements > Targeting**.
2. Select the **Project**, **Environment**, and **Flag** from the dropdowns.
3. Click **Create Rule**.
4. Build your rule conditions. Each condition has three parts:
   * **Attribute** -- what to evaluate. Common attributes include User ID, Email, Organization ID, Organization Name, Role, User Group, Country, Plan, App Version, and Platform.
   * **Operator** -- how to compare. Options include equals, does not equal, contains, does not contain, starts with, ends with, is one of, is not one of, greater than, and less than.
   * **Value** -- the value to compare against.
5. You can add multiple conditions to a single rule. All conditions must match for the rule to apply.
6. Set the **Value** the flag should return when the rule matches.
7. Set a **Priority** to control evaluation order when multiple rules exist. Lower numbers are evaluated first.
8. Click **Create**.

Rules are evaluated in priority order. The first matching rule determines the flag value. If no rules match, the default environment value is used.

### Setting Up Progressive Rollouts

Rollouts let you gradually release a flag to an increasing percentage of users over time.

1. Go to **Feature Entitlements > Rollouts**.
2. Click **Create Rollout**.
3. Select the **Project**, **Flag**, and **Environment**.
4. Set the **Start Percentage** (the initial percentage of users who receive the flag).
5. Set the **Target Percentage** (the final percentage to reach).
6. Set the **Duration** in hours for the rollout to progress from start to target.
7. Click **Create**.

Active rollouts can be paused, resumed, or cancelled. The rollouts page shows the current status of each rollout: Scheduled, In Progress, Paused, Completed, or Cancelled.

### Organization Overrides

Organization overrides let you set a flag value that applies only to users within a specific organization, regardless of the default environment value.

1. Go to **Feature Entitlements > Feature Flags**.
2. Select the project and click on the flag you want to override.
3. In the flag detail panel, look for the **Organization Scope** section.
4. Select the organization and set the override value.
5. Save the override.

This is useful for enabling a feature for a specific customer organization during a pilot or beta period.

### Managing SDK Keys

SDK keys are credentials your application uses to retrieve flag values from AccessIQ.

1. Go to **Feature Entitlements > SDK Keys**.
2. Select the **Project** and **Environment**.
3. Click **Create Key**.
4. Choose a **Type**:
   * **Server** -- full access, for backend services and APIs. Keep this key secret.
   * **Client** -- safe for browser applications. Exposes only flags marked as client-visible.
   * **Mobile** -- optimized for iOS and Android apps.
5. Enter a **Name** to identify the key.
6. Click **Create**.

The key value is displayed once after creation. Copy and store it securely. You can revoke a key at any time by clicking the delete icon.

### Org-Scoped Project Access

Access to feature flag projects is governed by the user's role and organization membership:

* **Owner** and **Super Admin** roles can see and edit all flags across all projects.
* **Admin** roles can see tenant-level flags and flags in organizations they have access to.
* **Manager** and other roles can view tenant-level flags and flags in their accessible organizations, but cannot make changes.

When a flag has organization overrides, it is considered org-scoped. Users who do not have access to any of the organizations in the override list will not see that flag.

### Viewing Entitlements

The **Access Control > Entitlements** page shows the resolved entitlements for the currently signed-in user. This page is useful for verifying that flags, roles, and organization access are configured correctly.

The page displays:

* **JWT claims** -- the full decoded access token, organized into categories: Standard Claims, Identity, Tenant and Session, Roles and Permissions, Organization Access, Feature Entitlements, Policy Decisions, and any Custom Claims.
* **Session claims** -- entitlements resolved from the server-side session, which may include additional context not present in the JWT.
* **Feature flags** -- a visual summary of which flags are enabled or disabled for the current user, with organization override information when applicable.

## Getting Started

1. [Create a project and environments](/accessiq-docs/feature-entitlements/projects-and-environments.md)
2. [Create and configure flags](/accessiq-docs/feature-entitlements/creating-flags.md)
3. [Set values per environment](/accessiq-docs/feature-entitlements/values-per-environment.md)
4. [Add targeting rules](/accessiq-docs/feature-entitlements/targeting-rules.md) (optional)
5. [Set up progressive rollouts](/accessiq-docs/feature-entitlements/rollouts.md) (optional)
6. [Integrate the SDK](/accessiq-docs/feature-entitlements/sdk-integration.md) in your application


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://accessiq.gitbook.io/accessiq-docs/feature-entitlements/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.