Unleash Service Accounts API
Endpoints for managing [Service Accounts](https://docs.getunleash.io/concepts/service-accounts), which enable programmatic access to the Unleash API.
OpenAPI Specification
openapi: 3.0.3
info:
title: Unleash Admin Addons Service Accounts 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: Service Accounts
description: Endpoints for managing [Service Accounts](https://docs.getunleash.io/concepts/service-accounts), which enable programmatic access to the Unleash API.
paths:
/api/admin/service-account:
get:
tags:
- Service Accounts
operationId: getServiceAccounts
summary: List Service Accounts.
description: '**Enterprise feature**
Returns the list of all service accounts.'
responses:
'200':
description: '#/components/schemas/serviceAccountsSchema'
content:
application/json:
schema:
$ref: '#/components/schemas/serviceAccountsSchema'
'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.
post:
tags:
- Service Accounts
operationId: createServiceAccount
summary: Create a Service Account.
description: '**Enterprise feature**
Creates a new service account.'
requestBody:
description: '#/components/schemas/createServiceAccountSchema'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/createServiceAccountSchema'
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/serviceAccountSchema'
'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.
'409':
description: The provided resource can not be created or updated because it would conflict with the current state of the resource or with an already existing resource, respectively.
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: NameExistsError
description: The name of the error kind
message:
type: string
example: There is already a feature called "my-awesome-feature".
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/service-account/{id}:
put:
tags:
- Service Accounts
operationId: updateServiceAccount
summary: Update a Service Account.
description: '**Enterprise feature**
Updates an existing service account identified by its id.'
requestBody:
description: '#/components/schemas/updateServiceAccountSchema'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/updateServiceAccountSchema'
responses:
'200':
description: '#/components/schemas/serviceAccountSchema'
content:
application/json:
schema:
$ref: '#/components/schemas/serviceAccountSchema'
'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.
'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.
'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.
parameters:
- name: id
in: path
required: true
schema:
type: string
delete:
tags:
- Service Accounts
operationId: deleteServiceAccount
summary: Delete a Service Account.
description: '**Enterprise feature**
Deletes an existing service account identified by its id.'
responses:
'200':
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.
'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.
'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.
parameters:
- name: id
in: path
required: true
schema:
type: string
/api/admin/service-account/{id}/token:
get:
tags:
- Service Accounts
operationId: getServiceAccountTokens
summary: List All Tokens for a Service Account.
description: '**Enterprise feature**
Returns the list of all tokens for a service account identified by the id.'
responses:
'200':
description: '#/components/schemas/patsSchema'
content:
application/json:
schema:
$ref: '#/components/schemas/patsSchema'
'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.
'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.
parameters:
- name: id
in: path
required: true
schema:
type: string
post:
tags:
- Service Accounts
operationId: createServiceAccountToken
summary: Create a Token for a Service Account.
description: '**Enterprise feature**
Creates a new token for the service account identified by the id.'
requestBody:
description: '#/components/schemas/createPatSchema'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/createPatSchema'
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/patSchema'
'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.
'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.
'409':
description: The provided resource can not be created or updated because it would conflict with the current state of the resource or with an already existing resource, respectively.
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: NameExistsError
description: The name of the error kind
message:
type: string
example: There is already a feature called "my-awesome-feature".
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.
parameters:
- name: id
in: path
required: true
schema:
type: string
/api/admin/service-account/{id}/token/{tokenId}:
delete:
tags:
- Service Accounts
operationId: deleteServiceAccountToken
summary: Delete a Token for a Service Account.
description: '**Enterprise feature**
Deletes a token for the service account identified both by the service account''s id and the token''s id.'
responses:
'200':
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.
'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.
'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.
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: tokenId
in: path
required: true
schema:
type: string
components:
schemas:
patsSchema:
type: object
description: Contains a collection of [personal access tokens](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#personal-access-tokens), or PATs. PATs are automatically scoped to the authenticated user.
properties:
pats:
type: array
description: A collection of PATs.
items:
$ref: '#/components/schemas/patSchema'
serviceAccountsSchema:
type: object
additionalProperties: false
required:
- serviceAccounts
description: Represents a list of service accounts, and includes a list of root roles they reference
properties:
serviceAccounts:
description: A list of service accounts
type: array
items:
$ref: '#/components/schemas/serviceAccountSchema'
rootRoles:
description: A list of root roles that are referenced from service account objects in the `serviceAccounts` list
type: array
items:
$ref: '#/components/schemas/roleSchema'
createPatSchema:
description: Describes the properties required to create a [personal access token](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#personal-access-tokens), or PAT. PATs are automatically scoped to the authenticated user.
type: object
required:
- description
- expiresAt
properties:
description:
type: string
description: The PAT's description.
example: user:xyzrandomstring
expiresAt:
type: string
format: date-time
description: The PAT's expiration date.
example: '2023-04-19T08:15:14.000Z'
createServiceAccountSchema:
type: object
required:
- username
- name
- rootRole
description: Describes the properties required to create a new service account
properties:
username:
type: string
description: The username of the service account
example: service-account-1
name:
type: string
description: The name of the service account
example: Service Account 1
rootRole:
type: integer
description: The id of the root role for the service account
example: 1
patSchema:
type: object
description: Describes a [personal access token](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#personal-access-tokens), or PAT. PATs are automatically scoped to the authenticated user.
required:
- id
- createdAt
- description
- expiresAt
properties:
id:
type: integer
description: The PAT's ID. PAT IDs are incrementing integers. In other words, a more recently created PAT will always have a higher ID than an older one.
example: 1
minimum: 1
secret:
type: string
description: The token used for authentication. It is automatically generated by Unleash when the PAT is created and that is the only time this property is returned.
example: user:xyzrandomstring
createdAt:
type: string
format: date-time
example: '2023-04-19T08:15:14.000Z'
description: The date and time of when the PAT was created.
seenAt:
type: string
format: date-time
nullable: true
example: '2023-04-19T08:15:14.000Z'
description: When the PAT was last seen/used to authenticate with. `null` if it has not been used yet.
userId:
type: integer
description: The ID of the user this PAT belongs to.
example: 1337
description:
type: string
description: The PAT's description.
example: user:xyzr
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unleash/refs/heads/main/openapi/unleash-service-accounts-api-openapi.yml