Unleash Instance Admin API
Instance admin endpoints used to manage the Unleash instance itself.
OpenAPI Specification
openapi: 3.0.3
info:
title: Unleash Admin Addons Instance Admin API
version: 7.4.1
description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons).
servers:
- url: https://app.unleash-instance.example.com
description: Your Unleash instance (replace with your actual URL)
security:
- apiKey: []
- bearerToken: []
tags:
- name: Instance Admin
description: Instance admin endpoints used to manage the Unleash instance itself.
paths:
/api/admin/logins:
get:
tags:
- Instance Admin
operationId: getLoginHistory
responses:
'200':
description: loginHistorySchema
content:
application/json:
schema:
$ref: '#/components/schemas/loginHistorySchema'
text/csv:
schema:
type: string
'204':
description: This response has no body.
'401':
description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: AuthenticationRequired
description: The name of the error kind
message:
type: string
example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
description: A description of what went wrong.
'404':
description: The requested resource was not found.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NotFoundError
description: The name of the error kind
message:
type: string
example: Could not find the addon with ID "12345".
description: A description of what went wrong.
description: '**Enterprise feature**
Returns **all** login events in the Unleash system. You can optionally get them in CSV format by specifying the `Accept` header as `text/csv`.'
summary: Get All Login Events.
/api/admin/license/check:
get:
tags:
- Instance Admin
operationId: checkLicense
summary: Validates the Unleash License.
description: '**Enterprise feature**
Validates the Unleash license.'
responses:
'200':
description: licenseCheckSchema
content:
application/json:
schema:
$ref: '#/components/schemas/licenseCheckSchema'
/api/admin/license:
get:
tags:
- Instance Admin
summary: Reads the Unleash License.
description: '**Enterprise feature**
Reads the Unleash license. Only available for self-hosted Enterprise customers.'
operationId: readLicense
responses:
'200':
description: licenseReadSchema
content:
application/json:
schema:
$ref: '#/components/schemas/licenseReadSchema'
post:
tags:
- Instance Admin
operationId: updateLicense
summary: Set a New Unleash License.
description: '**Enterprise feature**
Set a new Unleash license. Only available for self-hosted Enterprise customers.'
requestBody:
description: licenseUpdateSchema
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/licenseUpdateSchema'
responses:
'201':
headers:
location:
description: The location of the newly created resource.
schema:
type: string
format: uri
description: The resource was successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/licenseReadSchema'
'400':
description: The request data does not match what we expect.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ValidationError
description: The name of the error kind
message:
type: string
example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
description: A description of what went wrong.
'401':
description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: AuthenticationRequired
description: The name of the error kind
message:
type: string
example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
description: A description of what went wrong.
'403':
description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NoAccessError
description: The name of the error kind
message:
type: string
example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
description: A description of what went wrong.
'415':
description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTypeerror
description: The name of the error kind
message:
type: string
example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
description: A description of what went wrong.
/api/admin/instance-admin/statistics/csv:
get:
tags:
- Instance Admin
summary: Instance Usage Statistics
description: Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.
operationId: getInstanceAdminStatsCsv
responses:
'200':
description: instanceAdminStatsSchemaCsv
content:
text/csv:
example: '"OIDCenabled","SAMLenabled","passwordAuthEnabled","SCIMenabled","clientApps","contextFields","environments","featureExports","featureImports","featureToggles","archivedFeatureToggles","groups","instanceId","projects","roles","customRootRoles","customRootRolesInUse","segments","strategies","sum","timestamp","users","licensedUsers","serviceAccounts","apiTokens","versionEnterprise","versionOSS","activeUsers","productionChanges","previousDayMetricsBucketsCount","maxEnvironmentStrategies","maxConstraints","maxConstraintValues","releaseTemplates","releasePlans","edgeInstanceUsage","readOnlyUsers"
true,false,true,false,"[{""range"":""allTime"",""count"":15},{""range"":""30d"",""count"":9},{""range"":""7d"",""count"":5}]",6,2,0,0,29,10,3,"ed3861ae-78f9-4e8c-8e57-b57efc15f82b",4,5,2,1,2,8,"some-sha256-hash","2023-07-12T10:00:00.000Z",10,12,2,"{}","5.1.7","5.1.7","{""last90"":15,""last60"":12,""last30"":10,""last7"":5}","{""last30"":100,""last60"":200,""last90"":200}","{""variantCount"":100,""enabledCount"":200}",20,17,123,3,5,"{""2022-06"":2.345,""2022-07"":2.567,""2022-08"":2.789}",4'
schema:
type: string
/api/admin/instance-admin/statistics:
get:
tags:
- Instance Admin
operationId: getInstanceAdminStats
summary: Instance Usage Statistics
description: Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.
responses:
'200':
description: instanceAdminStatsSchema
content:
application/json:
schema:
$ref: '#/components/schemas/instanceAdminStatsSchema'
components:
schemas:
licenseReadSchema:
description: A model representing a license response.
type: object
additionalProperties: false
required:
- isValid
properties:
token:
description: The actual license token.
type: string
isValid:
description: Whether the license is valid or not.
type: boolean
customer:
description: Name of the customer that owns the license. This is the name of the company that purchased the license.
type: string
type:
description: Type of license.
type: string
instanceName:
description: Name of the Unleash instance where this license is valid.
type: string
instanceId:
description: Identifier of the Unleash instance where this license is valid.
type: string
plan:
description: Name of plan that the license is for.
type: string
resources:
type: object
description: The resources available in the license.
additionalProperties: false
properties:
seats:
description: Number of seats in the license.
type: number
releaseTemplates:
description: Number of release templates in the license.
type: number
edgeInstances:
description: Number of Edge instances in the license.
type: number
readOnlyUsers:
description: Number of read-only users in the license.
type: number
expireAt:
description: Date when the license expires.
type: string
format: date-time
example: '2023-07-31T13:33:02Z'
issuedAt:
description: Date when the license was issued.
type: string
format: date-time
example: '2023-07-31T13:33:02Z'
loginHistorySchema:
description: A response model with a list of login events.
type: object
additionalProperties: false
required:
- events
properties:
events:
type: array
description: A list of login events
items:
$ref: '#/components/schemas/loginEventSchema'
licenseUpdateSchema:
description: A model representing a set license token.
type: object
additionalProperties: false
required:
- token
properties:
token:
description: The actual license token.
type: string
loginEventSchema:
description: A model representing a single login event.
type: object
additionalProperties: false
required:
- id
properties:
id:
description: The event's ID. Event IDs are incrementing integers. In other words, a more recent event will always have a higher ID than an older event.
type: integer
minimum: 1
example: 13
username:
description: The username of the user that attempted to log in. Will return "Incorrectly configured provider" when attempting to log in using a misconfigured provider.
type: string
example: admin
auth_type:
description: The authentication type used to log in.
example: simple
type: string
created_at:
description: The date and time of when the login was attempted.
type: string
format: date-time
example: '2023-03-01T12:04:26.061Z'
successful:
description: Whether the login was successful or not.
type: boolean
example: true
ip:
description: The IP address of the client that attempted to log in.
type: string
nullable: true
example: ::ffff:127.0.0.1
failure_reason:
description: The reason for the login failure. This property is only present if the login was unsuccessful.
type: string
nullable: true
example: No user found
instanceAdminStatsSchema:
type: object
additionalProperties: false
description: Information about an instance and statistics about usage of various features of Unleash
required:
- instanceId
properties:
instanceId:
type: string
description: A unique identifier for this instance. Generated by the database migration scripts at first run. Typically a UUID.
example: ed3861ae-78f9-4e8c-8e57-b57efc15f82b
timestamp:
type: string
format: date-time
nullable: true
description: When these statistics were produced
example: '2023-06-12T12:25:06Z'
versionOSS:
type: string
description: The version of Unleash OSS that is bundled in this instance
example: 5.1.7
versionEnterprise:
type: string
description: The version of Unleash Enterprise that is bundled in this instance
example: 5.1.7
users:
type: integer
description: The number of users this instance has
example: 8
minimum: 0
previousDayMetricsBucketsCount:
type: object
description: 'The number client metrics buckets records recorded in the previous day. # features * # apps * # envs * # hours with metrics'
properties:
enabledCount:
type: integer
description: The number of enabled/disabled metrics buckets recorded in the previous day
example: 10
minimum: 0
variantCount:
type: integer
description: The number of variant metrics buckets recorded in the previous day
example: 10
minimum: 0
activeUsers:
type: object
description: The number of active users in the last 7, 30 and 90 days
properties:
last7:
type: integer
description: The number of active users in the last 7 days
example: 5
minimum: 0
last30:
type: integer
description: The number of active users in the last 30 days
example: 10
minimum: 0
last60:
type: integer
description: The number of active users in the last 60 days
example: 12
minimum: 0
last90:
type: integer
description: The number of active users in the last 90 days
example: 15
minimum: 0
licensedUsers:
type: integer
description: The number of users who had access to Unleash within the last 30 days, including those who may have been deleted during this period.
example: 10
minimum: 0
productionChanges:
type: object
description: The number of changes to the production environment in the last 30, 60 and 90 days
properties:
last30:
type: integer
description: The number of changes in production in the last 30 days
example: 10
minimum: 0
last60:
type: integer
description: The number of changes in production in the last 60 days
example: 12
minimum: 0
last90:
type: integer
description: The number of changes in production in the last 90 days
example: 15
minimum: 0
featureToggles:
type: integer
description: The number of feature-toggles this instance has
example: 47
minimum: 0
projects:
type: integer
description: The number of projects defined in this instance.
example: 3
minimum: 0
contextFields:
type: integer
description: The number of context fields defined in this instance.
example: 7
minimum: 0
roles:
type: integer
description: The number of roles defined in this instance
example: 5
minimum: 0
groups:
type: integer
description: The number of groups defined in this instance
example: 12
minimum: 0
environments:
type: integer
description: The number of environments defined in this instance
example: 3
minimum: 0
segments:
type: integer
description: The number of segments defined in this instance
example: 19
minimum: 0
strategies:
type: integer
description: The number of strategies defined in this instance
example: 8
minimum: 0
SAMLenabled:
type: boolean
description: Whether or not SAML authentication is enabled for this instance
example: false
OIDCenabled:
type: boolean
description: Whether or not OIDC authentication is enabled for this instance
example: true
clientApps:
type: array
description: A count of connected applications in the last week, last month and all time since last restart
items:
type: object
description: An entry describing how many client applications has been observed over the defined range
properties:
range:
type: string
description: A description of a time range
enum:
- allTime
- 30d
- 7d
example: 30d
count:
type: integer
description: The number of client applications that have been observed in this period
example: 1
featureExports:
type: integer
description: The number of export operations on this instance
example: 0
minimum: 0
featureImports:
type: integer
description: The number of import operations on this instance
example: 0
minimum: 0
apiTokens:
type: object
description: The number of API tokens in Unleash, split by type
properties:
admin:
type: integer
description: The number of admin tokens.
minimum: 0
example: 5
client:
type: integer
description: The number of client tokens.
minimum: 0
example: 5
frontend:
type: integer
description: The number of frontend tokens.
minimum: 0
example: 5
maxEnvironmentStrategies:
type: integer
minimum: 0
example: 3
description: The highest number of strategies used on a single feature flag in a single environment.
maxConstraints:
type: integer
minimum: 0
example: 4
description: The highest number of constraints used on a single strategy.
maxConstraintValues:
type: integer
minimum: 0
example: 17
description: The highest number of constraint values used on a single constraint.
releaseTemplates:
type: integer
minimum: 0
example: 2
description: The number of release templates in this instance
releasePlans:
type: integer
minimum: 0
example: 1
description: The number of release plans in this instance
edgeInstanceUsage:
type: object
description: The average number of edge instances, per month, in the last 12 months, rounded to 3 decimal places
additionalProperties:
type: number
minimum: 0
example:
2025-09: 2.25
2025-08: 1.75
2024-10: 0.45
readOnlyUsers:
type: integer
minimum: 0
example: 1
description: The number of ReadOnly users in this instance
sum:
type: string
description: A SHA-256 checksum of the instance statistics to be used to verify that the data in this object has not been tampered with
example: b023323477abb1eb145bebf3cdb30a1c2063e3edc1f7ae474ed8ed6c80de9a3b
licenseCheckSchema:
description: A model representing a license check response.
type: object
additionalProperties: false
required:
- isValid
properties:
isValid:
description: Whether or not the current Unleash license is considered valid
type: boolean
message:
description: Message describing the current state of the Unleash license
type: string
example: Your license expired 3 days ago
messageType:
description: Type of messages, whether it is an informative or a warning
type: string
example: info
enum:
- info
- warning
- error
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: API key needed to access this API
bearerToken:
type: http
scheme: bearer
description: API key needed to access this API, in Bearer token format