User settings

LaunchDarkly's User Settings API provides a picture of all feature flags and their current values for a specific user. This gives you instant visibility of how a particular user is experiencing your site or application.

The User Settings API can also be used to assign a user to a specific variation for any feature flag.

List flag settings for user

Get the current flag settings for a given user. The most important attribute in the response is the _value. The _value is the setting that the user sees. For a boolean feature toggle, this is true, false, or null. null returns if there is no defined fallthrough value. The example response indicates that the user Abbie_Braun has the sort.order flag enabled and the alternate.page flag disabled.

The setting attribute indicates whether you've explicitly targeted a user to receive a particular variation. For example, if you have turned off a feature flag for a user, this setting will be false. A setting of null means that you haven't assigned that user to a specific variation.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key

envKey
required
string <string>

The environment key

key
required
string <string>

The user key

Responses
200

User flag settings collection response

400

Invalid request body

401

Invalid access token

403

Forbidden

404

Invalid resource specifier

429

Rate limited

get/api/v2/users/{projKey}/{envKey}/{key}/flags
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/users/:projKey/:envKey/:key/flags \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "items": {
    },
  • "_links": {
    }
}

Get flag setting for user

Get a single flag setting for a user by key. The most important attribute in the response is the _value. The _value is the current setting that the user sees. For a boolean feature toggle, this is true, false, or null. null returns if there is no defined fallback value. The example response indicates that the user Abbie_Braun has the sort.order flag enabled.

The setting attribute indicates whether you've explicitly targeted a user to receive a particular variation. For example, if you have turned off a feature flag for a user, this setting will be false. A setting of null means that you haven't assigned that user to a specific variation.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key

envKey
required
string <string>

The environment key

key
required
string <string>

The user key

featureKey
required
string <string>

The feature flag key

Responses
200

User flag settings response

400

Invalid request body

401

Invalid access token

403

Forbidden

404

Invalid resource specifier

429

Rate limited

get/api/v2/users/{projKey}/{envKey}/{key}/flags/{featureKey}
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/users/:projKey/:envKey/:key/flags/:featureKey \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "_links": {
    },
  • "_value": "true",
  • "setting": "null"
}

Update flag settings for user

Enable or disable a feature flag for a user based on their key.

To change the setting, send a PUT request to this URL with a request body containing the flag value. For example, to disable the sort.order flag for the user test@test.com, send a PUT to https://app.launchdarkly.com/api/v2/users/default/production/test@test.com/flags/sort.order with the following body:

{
  "setting": false
}

Omitting the setting attribute, or a setting of null, in your PUT "clears" the current setting for a user.

If you previously patched the flag, and the patch included the user's data, LaunchDarkly continues to use that data. If LaunchDarkly has never encountered the user's key before, it calculates the flag values based on the user key alone.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key

envKey
required
string <string>

The environment key

key
required
string <string>

The user key

featureKey
required
string <string>

The feature flag key

Request Body schema: application/json
setting
any

The variation value to set for the user

comment
string
Responses
204

Action completed successfully

400

Invalid request body

401

Invalid access token

403

Forbidden

404

Invalid resource specifier

429

Rate limited

put/api/v2/users/{projKey}/{envKey}/{key}/flags/{featureKey}
Request samples
application/json
{
  • "setting": null,
  • "comment": "string"
}

Get expiring dates on flags for user

Get a list of flags for which the given user is scheduled for removal.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

userKey
required
string <string>

The user key.

envKey
required
string <string>

The environment key.

Responses
200

User targeting expirations on feature flag response.

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/users/{projKey}/{userKey}/expiring-user-targets/{envKey}
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/users/:projKey/:userKey/expiring-user-targets/:envKey \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Update expiring user target for flags

Schedule the specified user for removal from individual user targeting on one or more flags. You can only schedule a user for removal on a single variation per flag.

To learn more about semantic patches, read Updates.

If you previously patched the flag, and the patch included the user's data, LaunchDarkly continues to use that data. If LaunchDarkly has never encountered the user's key before, it calculates the flag values based on the user key alone.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

userKey
required
string <string>

The user key.

envKey
required
string <string>

The environment key.

Request Body schema: application/json
required
Array of objects (JSONPatch)
comment
string
Responses
200

User targeting expirations on feature flag response.

400

Invalid request body

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

patch/api/v2/users/{projKey}/{userKey}/expiring-user-targets/{envKey}
Request samples
application/json
{
  • "patch": [
    ],
  • "comment": "string"
}
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalInstructions": 0,
  • "successfulInstructions": 0,
  • "failedInstructions": 0,
  • "errors": [
    ]
}