Manage user identities within an environment. Identities represent individual users and their associated traits.
openapi: 3.1.0
info:
title: Flagsmith Admin Environments Identities API
description: The Flagsmith Admin API allows developers to programmatically manage all aspects of their Flagsmith projects. Anything that can be done through the Flagsmith dashboard can also be accomplished via this API, including creating, updating, and deleting projects, environments, feature flags, segments, and users. It uses a secret Organisation API Token for authentication and provides a Swagger interface at api.flagsmith.com/api/v1/docs for interactive exploration.
version: '1.0'
contact:
name: Flagsmith Support
url: https://www.flagsmith.com/contact-us
termsOfService: https://www.flagsmith.com/terms-of-service
servers:
- url: https://api.flagsmith.com/api/v1
description: Flagsmith Production API
security:
- apiKeyAuth: []
tags:
- name: Identities
description: Manage user identities within an environment. Identities represent individual users and their associated traits.
paths:
/environments/{environment_api_key}/identities/:
get:
operationId: listIdentities
summary: List identities for an environment
description: Retrieves a paginated list of all user identities within a specific environment. Identities represent individual users with their associated traits and flag overrides.
tags:
- Identities
parameters:
- $ref: '#/components/parameters/EnvironmentApiKey'
responses:
'200':
description: Successful response containing a list of identities
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse'
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Environment not found
/environments/{environment_api_key}/identities/{identity_id}/:
get:
operationId: getIdentity
summary: Get an identity
description: Retrieves the details of a specific identity by its ID within an environment, including its identifier and associated traits.
tags:
- Identities
parameters:
- $ref: '#/components/parameters/EnvironmentApiKey'
- $ref: '#/components/parameters/IdentityId'
responses:
'200':
description: Successful response containing the identity details
content:
application/json:
schema:
$ref: '#/components/schemas/Identity'
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Identity or environment not found
delete:
operationId: deleteIdentity
summary: Delete an identity
description: Permanently deletes an identity and all associated traits and flag overrides from an environment. This action cannot be undone.
tags:
- Identities
parameters:
- $ref: '#/components/parameters/EnvironmentApiKey'
- $ref: '#/components/parameters/IdentityId'
responses:
'204':
description: Identity deleted successfully
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Identity or environment not found
/identities/:
get:
operationId: getIdentityFlags
summary: Get flags and traits for an identity
description: Retrieves all feature flags and traits for a specific user identity. The flags returned may differ from the environment defaults based on the identity's traits and segment membership. If the identity does not exist, it will be created. This endpoint also supports transient identities and traits that are used for evaluation but not persisted.
tags:
- Identities
parameters:
- $ref: '#/components/parameters/IdentifierQuery'
- $ref: '#/components/parameters/TransientQuery'
responses:
'200':
description: Successful response containing flags and traits for the identity
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityResponse'
'400':
description: Bad request - missing identifier parameter
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing Environment Key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: identifyUserAndGetFlags
summary: Identify a user and get flags with traits
description: Identifies a user by providing an identifier and optional traits in the request body. Returns the evaluated flags for that identity based on the provided traits and any existing traits. Traits provided in the request body are persisted for the identity unless marked as transient. This endpoint performs the entire SDK identity workflow in a single call.
tags:
- Identities
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityRequest'
responses:
'200':
description: Successful response containing evaluated flags and persisted traits
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityResponse'
'400':
description: Bad request - missing or invalid identifier
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing Environment Key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/traits/:
post:
operationId: setTraits
summary: Set traits for an identity
description: Sets one or more trait values for a given identity. If the identity does not exist, it will be created. Traits are key-value pairs associated with an identity that can be used for segment evaluation and personalized flag delivery.
tags:
- Identities
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TraitRequest'
responses:
'200':
description: Successful response confirming the trait was set
content:
application/json:
schema:
$ref: '#/components/schemas/Trait'
'400':
description: Bad request - missing or invalid trait data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing Environment Key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/traits/bulk/:
put:
operationId: setBulkTraits
summary: Set multiple traits for an identity in bulk
description: Sets multiple trait values for a given identity in a single API call. This is more efficient than making individual trait requests when updating multiple traits at once. If a trait value is set to null, the trait will be deleted.
tags:
- Identities
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TraitRequest'
responses:
'200':
description: Successful response confirming the traits were set
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Trait'
'400':
description: Bad request - missing or invalid trait data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing Environment Key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
TraitInput:
type: object
description: Input object for setting a trait value on an identity.
required:
- trait_key
- trait_value
properties:
trait_key:
type: string
description: The key name of the trait to set
trait_value:
description: The value to set for the trait. Can be a string, integer, float, or boolean. Set to null to delete the trait.
oneOf:
- type: string
- type: integer
- type: number
- type: boolean
- type: 'null'
transient:
type: boolean
description: When true, this trait is transient and will be used for evaluation but not persisted.
IdentityRequest:
type: object
description: The request body for identifying a user and optionally setting traits.
required:
- identifier
properties:
identifier:
type: string
description: The unique identifier for the user identity in your application.
traits:
type: array
description: An optional array of traits to set for this identity. Traits are used for segment evaluation and personalized flag delivery.
items:
$ref: '#/components/schemas/TraitInput'
transient:
type: boolean
description: When true, the identity is transient and will not be persisted.
TraitRequest:
type: object
description: Request body for setting a trait on an identity.
required:
- identity
- trait_key
- trait_value
properties:
identity:
type: object
description: The identity to set the trait on
required:
- identifier
properties:
identifier:
type: string
description: The unique identifier for the user identity
trait_key:
type: string
description: The key name of the trait to set
trait_value:
description: The value to set for the trait. Set to null to delete the trait.
oneOf:
- type: string
- type: integer
- type: number
- type: boolean
- type: 'null'
IdentityResponse:
type: object
description: The response object for an identity flags request, containing the evaluated flags and traits for the specified identity.
properties:
flags:
type: array
description: The evaluated feature flags for this identity
items:
$ref: '#/components/schemas/Flag'
traits:
type: array
description: The traits associated with this identity
items:
$ref: '#/components/schemas/Trait'
Trait:
type: object
description: A trait is a key-value pair associated with an identity, used for segment evaluation and personalization.
properties:
id:
type: integer
description: The unique identifier for this trait
trait_key:
type: string
description: The key name of the trait
trait_value:
description: The value of the trait. Can be a string, integer, float, or boolean.
oneOf:
- type: string
- type: integer
- type: number
- type: boolean
Flag:
type: object
description: A feature flag object containing the feature definition, its enabled state, and any associated value for the environment.
properties:
id:
type: integer
description: The unique identifier for this feature state
feature:
$ref: '#/components/schemas/Feature'
feature_state_value:
description: The value associated with this feature state. Can be a string, integer, boolean, or null depending on the feature configuration.
oneOf:
- type: string
- type: integer
- type: boolean
- type: 'null'
enabled:
type: boolean
description: Whether this feature flag is currently enabled
environment:
type: integer
description: The ID of the environment this flag belongs to
identity:
type: integer
nullable: true
description: The identity ID if this is an identity-specific override, or null for environment defaults
feature_segment:
type: integer
nullable: true
description: The feature segment ID if this flag state is a segment override, or null otherwise
Identity:
type: object
description: A user identity within an environment, representing an individual user with their associated traits.
properties:
id:
type: integer
description: The unique identifier for this identity
identifier:
type: string
description: The user-provided identifier for this identity
environment:
type: integer
description: The ID of the environment this identity belongs to
PaginatedResponse:
type: object
description: A paginated response wrapper containing the results count and navigation links.
properties:
count:
type: integer
description: The total number of results
next:
type: string
nullable: true
format: uri
description: URL to the next page of results
previous:
type: string
nullable: true
format: uri
description: URL to the previous page of results
results:
type: array
description: The array of result objects for this page
items:
type: object
Feature:
type: object
description: A feature definition containing metadata about the feature flag including its name, type, and default configuration.
properties:
id:
type: integer
description: The unique identifier for this feature
name:
type: string
description: The name of the feature flag
created_date:
type: string
format: date-time
description: The date and time the feature was created
description:
type: string
nullable: true
description: A human-readable description of the feature
initial_value:
type: string
nullable: true
description: The initial value assigned to the feature when created
default_enabled:
type: boolean
description: Whether the feature is enabled by default
type:
type: string
enum:
- STANDARD
- MULTIVARIATE
description: The type of feature flag. STANDARD for simple on/off flags, MULTIVARIATE for flags with multiple value variations.
Error:
type: object
description: An error response from the API
properties:
detail:
type: string
description: A human-readable error message
parameters:
TransientQuery:
name: transient
in: query
description: When set to true, the identity is treated as transient and will not be persisted. The identity will be used for flag evaluation only.
required: false
schema:
type: boolean
IdentifierQuery:
name: identifier
in: query
description: The unique identifier for the user identity. This is typically a user ID, email, or other unique string that identifies the user in your application.
required: true
schema:
type: string
EnvironmentApiKey:
name: environment_api_key
in: path
description: The API key for the environment
required: true
schema:
type: string
IdentityId:
name: identity_id
in: path
description: The unique identifier for the identity
required: true
schema:
type: integer
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: A secret Organisation API Token prefixed with 'Api-Key'. For example, 'Api-Key your-token-here'. This token should never be exposed in client-side code.
externalDocs:
description: Flagsmith Admin API Documentation
url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api