Resolve Flags

Resolving flags means getting the value of a flag for a given evaluation context. The evaluation context contains information about the user, device, or other contextual data that Confidence uses to determine which variant to return.

Before You Begin

Before resolving flags, you need:

While you can resolve flags directly using the API as shown here, the most efficient way is using one of the Confidence SDKs. The SDKs handle caching, batching, and other optimizations automatically.

Authentication

Resolve operations use client secrets for authentication, not Bearer tokens:

curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": { ... }
  }'

Evaluation Context

The evaluation context specifies contextual data that Confidence uses to evaluate rules. It’s a schema-less key-value map (JSON object) containing any data needed for rule evaluation, such as:

User identifiers
User attributes (country, age, plan level)
Device information (OS, model, browser)
Session data (URL, referrer, timestamp)

Example evaluation context:

{
  "user_id": "rosling",
  "country": "SE",
  "device": {
    "vendor": "apple",
    "os": "ios"
  }
}

Do not pass sensitive data in the keys of the evaluation context. Values are never stored, but keys are temporarily stored to help derive the schema for targeting.

Batch Resolve (Recommended)

The recommended approach is to batch resolve all flags for a client. This returns values for all flags associated with the client:

curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": {
      "user_id": "rosling",
      "country": "SE",
      "device": {
        "vendor": "apple",
        "os": "ios"
      }
    }
  }'

Response:

{
  "resolvedFlags": [
    {
      "flag": "flags/button-colors",
      "variant": "",
      "value": {},
      "flagSchema": {
        "schema": {}
      },
      "reason": "RESOLVE_REASON_NO_SEGMENT_MATCH"
    },
    {
      "flag": "flags/image-size",
      "variant": "flags/image-size/variants/control",
      "value": {
        "name": "costello",
        "img-size": 42
      },
      "flagSchema": {
        "schema": {
          "name": {
            "stringSchema": {}
          },
          "img-size": {
            "intSchema": {}
          }
        }
      },
      "reason": "RESOLVE_REASON_MATCH"
    }
  ],
  "resolveToken": "<resolve token>"
}

Keep the resolveToken from the response. You’ll need it when applying flags to track usage.

Resolve Specific Flags

You can limit the resolve operation to specific flags using the flags parameter:

curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "flags": ["flags/image-size", "flags/button-colors"],
    "evaluationContext": {
      "user_id": "rosling",
      "country": "SE"
    }
  }'

This returns only the specified flags, which can reduce response size and processing time.

Understand Resolve Reasons

Each resolved flag includes a reason field explaining why it resolved the way it did:

Reason	Description
`RESOLVE_REASON_MATCH`	A rule matched and assigned a variant
`RESOLVE_REASON_NO_SEGMENT_MATCH`	No rule matched the evaluation context
`RESOLVE_REASON_FLAG_ARCHIVED`	The flag is archived
`RESOLVE_REASON_ERROR`	An error occurred during resolution

Test Resolve Logic

To test your resolve logic with different evaluation contexts:

Vary the context: Try different user IDs, countries, device types
Check reasons: Look at the reason field to understand why each flag resolved as it did
Verify variants: Ensure the returned variants match your expectations
Test edge cases: Try missing fields, null values, unexpected data types

Example testing different contexts:

# Test user from Sweden
curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": {
      "user_id": "user123",
      "country": "SE"
    }
  }'

# Test user from US
curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": {
      "user_id": "user456",
      "country": "US"
    }
  }'

Handle No Match

When no rule matches, the flag returns with RESOLVE_REASON_NO_SEGMENT_MATCH and empty values:

{
  "flag": "flags/my-flag",
  "variant": "",
  "value": {},
  "reason": "RESOLVE_REASON_NO_SEGMENT_MATCH"
}

Your application should handle this case by:

Using a default value specified in your code
Falling back to the original behavior
Logging the no-match event for debugging

Best Practices

Batch resolve: Always resolve all flags in one call to minimize network overhead
Cache locally: Cache resolved values to avoid repeated API calls
Provide complete context: Include all relevant fields that your targeting rules might use
Handle failures gracefully: Have fallback values if the resolve call fails
Use consistent keys: Ensure the targeting_key (or custom field) is stable for each user

Next Steps

After resolving flags:

Use the variant values in your application
Apply the flags to track usage and enable experiment analysis
Monitor resolve patterns and optimize your rules as needed

Get Started

Feature Flags

Metrics

Stats

Experiments

Surfaces

IAM

Connectors

Before You Begin

Authentication

Evaluation Context

Batch Resolve (Recommended)

Resolve Specific Flags

Understand Resolve Reasons

Test Resolve Logic

Handle No Match

Best Practices

Next Steps

​Before You Begin

​Authentication

​Evaluation Context

​Batch Resolve (Recommended)

​Resolve Specific Flags

​Understand Resolve Reasons

​Test Resolve Logic

​Handle No Match

​Best Practices

​Next Steps

Before You Begin

Authentication

Evaluation Context

Batch Resolve (Recommended)

Resolve Specific Flags

Understand Resolve Reasons

Test Resolve Logic

Handle No Match

Best Practices

Next Steps