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
200User flag settings collection response
400Invalid request body
401Invalid access token
403Forbidden
404Invalid resource specifier
429Rate 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
200User flag settings response
400Invalid request body
401Invalid access token
403Forbidden
404Invalid resource specifier
429Rate 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
204Action completed successfully
400Invalid request body
401Invalid access token
403Forbidden
404Invalid resource specifier
429Rate 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
200User targeting expirations on feature flag response.
401Invalid access token
403Forbidden
404Invalid resource identifier
429Rate 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
200User targeting expirations on feature flag response.
400Invalid request body
401Invalid access token
403Forbidden
404Invalid resource identifier
429Rate 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": [
    ]
}