Concepts
The terms Toggld uses for workspaces, environments, flags, targeting, evaluation, and credentials.
This page defines the terms that the rest of the documentation uses. Each section links to a detailed guide.
Workspace
A workspace is the top-level container for your team's flags. It holds environments, flags, segments, credentials, members, and the audit log. Workspaces are fully isolated from each other. The same flag key can exist in two workspaces without any relation.
In the API, a workspace is also called a tenant. The API never takes a tenant ID in the URL or the request body. It derives the workspace from the credential that you send. See Authentication.
During the beta, a workspace can hold up to ten flags.
Environment
An environment is a separate configuration space inside a workspace, such as Development or Production. New workspaces start with Development and Production, in that order. You can rename, add, reorder, and delete environments. The dashboard opens the first environment. See Environments.
Every credential belongs to exactly one environment. The credential selects the environment. You never put the environment in an evaluation request.
Flag
A flag is a named value that your code reads at runtime. Each flag has:
| Part | Scope | Description |
|---|---|---|
| Key | Shared | The identifier your code uses, such as new-checkout. It cannot change after creation. |
| Type | Shared | boolean, string, number, or object. It cannot change after creation. |
| Name, description, tags, metadata | Shared | Descriptive fields. Tags help you filter the flag list. |
| Variants | Per environment | The named values that the flag can serve. |
| Default variant | Per environment | The variant served when the flag is on and no rule matches. |
| Off variant | Per environment | The variant served when the flag is off. If you do not set one, Toggld uses the default variant. |
| Enabled | Per environment | Whether the flag is on in this environment. |
| Targeting rules | Per environment | Ordered rules that select a variant for matching users. |
"Shared" fields are the same in every environment. "Per environment" fields can differ between environments. See Create and edit flags.
Variant
A variant is one named value of a flag. For example, a string flag checkout-theme can have the variants light with the value "light" and dark with the value "dark". Every variant value must match the flag type. Boolean flags that you create with New flag in the dashboard have the variants true and false.
Targeting rule
A targeting rule serves a variant to the users that match it. A rule has conditions, optional segment references, and a serve action. Toggld checks the rules from top to bottom, and the first matching rule wins. A rule can serve one fixed variant or a percentage rollout. See Targeting rules.
Segment
A segment is a reusable audience, such as "beta testers" or "internal staff". A segment matches a user by rules, by a list of member keys, or both. Targeting rules can require that a user is in, or not in, a segment. Segments belong to the workspace and apply in every environment. See Segments.
Evaluation context and targeting key
The evaluation context is the set of attributes that you send with each evaluation. For example:
{ "targetingKey": "user-123", "plan": "pro", "country": "DE", "age": 34 }The targeting key (targetingKey) identifies the subject of the evaluation, usually a user ID. Percentage rollouts use it to put each subject in a stable bucket. Use a stable, non-empty string.
Conditions compare context attributes by their JSON type. The string "34" and the number 34 are different values. See operand types.
Evaluation and reasons
Evaluation is the process that turns a flag, an environment, and a context into a value. Toggld evaluates in this order:
- If the flag is off, serve the off variant. The reason is
DISABLED. - Otherwise, check each targeting rule in order. The first rule that matches serves its variant (reason
TARGETING_MATCH) or its rollout (reasonSPLIT). - If no rule matches, serve the default variant. The reason is
STATIC.
If evaluation fails, the reason is ERROR and the result has an error code, such as FLAG_NOT_FOUND or TARGETING_KEY_MISSING. The SDK then returns the fallback value that you supplied in code. See Errors.
| Reason | Meaning |
|---|---|
STATIC | The flag is on and no rule matched. Toggld served the default variant. |
TARGETING_MATCH | A rule matched and served a fixed variant. |
SPLIT | A rule matched and served a variant from a percentage rollout. |
DISABLED | The flag is off. Toggld served the off variant. |
ERROR | Evaluation failed. Your code receives its fallback value. |
Credentials
Toggld has three kinds of credentials. Each one belongs to one environment.
| Credential | Prefix | Secret | What it can do |
|---|---|---|---|
Server SDK key (evaluation role) | ffk_ | Yes | Evaluate flags and download full flag definitions for local evaluation. It cannot change anything. |
Management key (management role) | ffk_ | Yes | Everything a server SDK key can do, plus read and change flags, segments, environments, and keys through the Management API. |
| Public token | ffp_ | No | Evaluate flags from browsers and mobile apps. It cannot read flag definitions or change anything. |
Secret keys are shown once when you create them. Public tokens are non-secret, and each environment has exactly one. See API keys.
Remote and local evaluation
The Node.js SDK can evaluate flags in two ways:
- Remote evaluation sends each evaluation to the Toggld API, which returns the result. It is the default.
- Local evaluation downloads the flag definitions for the environment and evaluates them inside your process. Updates arrive in the background. There is no request per evaluation. It is the recommended mode for long-lived servers and requires a secret key.
Both modes use the same evaluation engine, so they return the same results for the same definitions. See Local evaluation.