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:xyzrandomstring
        expiresAt:
          type: string
          format: date-time
          description: The PAT's expiration date.
          example: '2023-04-19T08:15:14.000Z'
    updateServiceAccountSchema:
      type: object
      description: Describes the properties required to update a service account
      additionalProperties: true
      properties:
        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
    serviceAccountSchema:
      type: object
      additionalProperties: false
      required:
      - id
      description: Represents a [service account](https://docs.getunleash.io/concepts/service-accounts). Service accounts are used to let systems interact with the Unleash API.
      properties:
        id:
          type: number
          description: The service account id
          example: 54321
        isAPI:
          type: boolean
          deprecated: true
          example: false
          description: 'Deprecated: for internal use only, should not be exposed through the API'
        name:
          type: string
          description: The name of the service account
          example: My Service Account
        email:
          type: string
          example: noemail@getunleash.io
          deprecated: true
          description: 'Deprecated: service accounts don''t have emails associated with them'
        username:
          type: string
          description: The service account username
          example: my-service-account
        imageUrl:
          type: string
          description: The service account image url
          example: https://example.com/my-service-account.png
        inviteLink:
          type: string
          deprecated: true
          example: https://example.com/invite-link
          description: 'Deprecated: service accounts cannot be invited via an invitation link'
        loginAttempts:
          type: number
          deprecated: true
          example: 0
          description: 'Deprecated: service accounts cannot log in to Unleash'
        emailSent:
          type: boolean
          deprecated: true
          example: false
          description: 'Deprecated: internal use only'
        rootRole:
          type: integer
          description: The root role id associated with the service account
          example: 1
        seenAt:
          type: string
          format: date-time
          example: null
          nullable: true
          deprecated: true
          description: Deprecated. This property is always `null`. To find out when a service account was last seen, check its `tokens` list and refer to each token's `lastSeen` property instead.
        createdAt:
          type: string
          format: date-time
          description: The service account creation date
          example: '2021-01-01T00:00:00.000Z'
        tokens:
          type: array
          description: The list of tokens associated with the service account
          items:
            $ref: '#/components/schemas/patSchema'
    roleSchema:
      type: object
      description: A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform
      additionalProperties: false
      required:
      - id
      - type
      - name
      properties:
        id:
          type: integer
          description: The role id
          example: 9
          minimum: 0
        type:
          description: A role can either be a global root role (applies to all projects) or a project role
          type: string
          example: root
        name:
          description: The name of the role
          type: string
          example: Editor
        description:
          description: A more detailed description of the role and what use it's intended for
          type: string
          example: Users with the editor role have access to most features in Unleash but can not manage users and roles in the global scope. Editors will be added as project owners when creating projects and get superuser rights within the context of these projects. Users with the editor role will also get access to most permissions on the default project by default.
        project:
          description: What project the role belongs to
          type: string
          nullable: true
          example: default
  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