openapi: 3.2.0
info:
  version: 7.0.100
  title: Administrative Users API
  description: "Manage users, accounts, and account groups in the ThousandEyes platform using the Administrative API.\nThis API provides the following operations to manage your organization: \n\n  * `/account-groups`: Account groups are used to divide an organization into different sections. These operations can be used to create, retrieve, update and delete account groups.\n  * `/users`: Create, retrieve, update and delete users within an organization. \n  * `/roles`: Create, retrieve and update roles for the current user. \n  * `/permissions`: Retrieve all assignable permissions. Used in the context of modifying roles. \n  * `/audit-user-events`: Retrieve all activity log events.\n\n  For more information about the administrative models, see [Account Management](https://docs.thousandeyes.com/product-documentation/user-management)."
  x-provenance:
    method: harvested
    authored_by: Cisco ThousandEyes
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 27 OpenAPI 3.0 documents (26 per-area plus a unified 326-operation document) served anonymously from Cisco's DevNet CDN. api.thousandeyes.com itself 401s every path, so the contract is public while the API host is gated.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/000-v7-apis/docs/reference/
  - type: source
    url: https://developer.cisco.com/docs/thousandeyes/
servers:
- description: ThousandEyes API production URL
  url: https://api.thousandeyes.com/v7
security:
- BearerAuth: []
tags:
- name: Users
  description: User CRUD operations
paths:
  /users:
    get:
      tags:
      - Users
      summary: List users
      operationId: getUsers
      description: Retrieves a list of users in the organization the account group ID belongs to. This operation requires the `API Access` and `View all users` permissions. See [Account Context](https://developer.thousandeyes.com/v7/#/accountcontext) for more information on changing the account group context.
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Users'
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
      - Users
      summary: Create user
      operationId: createUser
      description: "Creates a new user.\n\nThe following applies when creating a user: \n* If the user is already a member of another ThousandEyes customer organization, the user must set their own login account group. \n* Any update that includes `accountGroupRoles` is a replace-based update and not a delta-based update."
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
        required: true
      responses:
        '201':
          description: Created
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CreatedUser'
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedUser'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /users/{id}:
    get:
      tags:
      - Users
      summary: Retrieve user
      operationId: getUser
      description: Retrieves detailed information about a user. This operation requires the `API Access` and `View All Users` permissions.
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/UserDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    put:
      tags:
      - Users
      summary: Update user
      operationId: updateUser
      description: "Updates a user using the user ID. You can update the user name, email address, account group assignments, or roles. This operation requires the `Edit users in all account groups` or `Edit users` permission. \n\nWhen updating a user, the following applies:\n* When updating a user's email address, the user must confirm the username change before they can subsequently log in or perform API operations.\n* Any update that includes `accountGroupRoles` is a replace-based update and not a delta-based update."
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/AccountGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/UserDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
      - Users
      summary: Delete user
      operationId: deleteUser
      description: Deletes a user using the user ID. This operation requires the `Edit users in all account groups` or `Edit users` permission.
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /users/current:
    get:
      tags:
      - Users
      summary: Retrieve current user
      operationId: getCurrentUser
      description: Retrieves detailed information about the current user.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/UserDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    UserAccountGroupRole:
      type: object
      properties:
        accountGroupId:
          type: string
          description: Unique ID of the account group.
          example: '315'
        roleIds:
          type: array
          description: Unique role IDs.
          items:
            type: string
            description: Unique role ID.
            example: '57'
          example:
          - '57'
          - '1140'
    ValidationError:
      type: object
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          errors:
            type:
            - array
            - 'null'
            description: (Optional) When multiple errors occur, the details for each error are listed.
            items:
              $ref: '#/components/schemas/ValidationErrorItem'
    CreatedUser:
      allOf:
      - $ref: '#/components/schemas/User'
      - type: object
        properties:
          loginAccountGroup:
            $ref: '#/components/schemas/AccountGroup'
          accountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/AccountGroupRole'
          allAccountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/Role'
          _links:
            $ref: '#/components/schemas/SelfLinks'
    ExtendedUser:
      allOf:
      - $ref: '#/components/schemas/User'
      - type: object
        properties:
          lastLogin:
            type: string
            description: UTC last login of the user (ISO date-time format).
            format: date-time
            example: '2022-07-17T22:00:54Z'
    AccountGroupRole:
      type: object
      properties:
        accountGroup:
          $ref: '#/components/schemas/AccountGroup'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    ValidationErrorItem:
      type: object
      properties:
        code:
          type: string
          description: (Optional) A unique error type/code that can be referenced in the documentation for further details.
        field:
          type: string
          description: Identifies the field that triggered this particular error.
        message:
          type: string
          description: A short, human-readable summary of the error.
    BaseRole:
      type: object
      properties:
        name:
          type: string
          description: Name of the role.
          example: Organization Admin
        roleId:
          type: string
          description: Unique ID representing the role.
          example: '35'
        isBuiltin:
          type: boolean
          description: Flag indicating if the role is built-in (Account Admin, Organization Admin, Regular User).
    Users:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/ExtendedUser'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        error_description:
          type: string
          example: Invalid access token
    Link:
      type: object
      description: A hyperlink from the containing resource to a URI.
      required:
      - href
      properties:
        href:
          type: string
          description: Its value is either a URI [RFC3986] or a URI template [RFC6570].
          example: https://api.thousandeyes.com/v7/link/to/resource/id
        templated:
          type: boolean
          description: Should be true when the link object's "href" property is a URI template.
        type:
          type: string
          description: Used as a hint to indicate the media type expected when dereferencing the target resource.
        deprecation:
          type: string
          description: Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation.
        name:
          type: string
          description: Its value may be used as a secondary key for selecting link objects that share the same relation type.
        profile:
          type: string
          description: A URI that hints about the profile of the target resource.
        title:
          type: string
          description: Intended for labelling the link with a human-readable identifier
        hreflang:
          type: string
          description: Indicates the language of the target resource
    Role:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseRole'
      - properties:
          hasManagementPermissions:
            type: boolean
            description: Flag indicating whether the user has management permissions.
    User:
      type: object
      properties:
        name:
          type: string
          description: User's display name.
          example: User X
        email:
          type: string
          description: User's email address.
          format: email
          example: userx@thousandeyes.com
        uid:
          type: string
          description: Unique ID of the user.
          example: '245'
        dateRegistered:
          type: string
          description: UTC date the user registered their account (ISO date-time format).
          format: date-time
          example: '2020-07-17T22:00:54Z'
        loginAccountGroup:
          $ref: '#/components/schemas/AccountGroup'
    UserRequest:
      type: object
      properties:
        name:
          type: string
          description: User's display name.
          example: User X
        email:
          type: string
          description: User's email address.
          format: email
          example: userx@thousandeyes.com
        loginAccountGroupId:
          type: string
          description: Unique ID of the login account group.
          example: '691'
        accountGroupRoles:
          type: array
          items:
            $ref: '#/components/schemas/UserAccountGroupRole'
        allAccountGroupRoleIds:
          type: array
          description: Unique IDs representing the roles.
          items:
            type: string
            description: Unique role ID.
            example: '57'
          example:
          - '57'
          - '1140'
    Error:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. When this member is not present, its value is assumed to be "about:blank".
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.
    AccountGroup:
      type: object
      properties:
        aid:
          $ref: '#/components/schemas/AccountGroupId'
        accountGroupName:
          type: string
          description: Account group name
          example: Account A
    UserDetail:
      allOf:
      - $ref: '#/components/schemas/ExtendedUser'
      - type: object
        properties:
          loginAccountGroup:
            $ref: '#/components/schemas/AccountGroup'
          accountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/AccountGroupRole'
          allAccountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/Role'
          _links:
            $ref: '#/components/schemas/SelfLinks'
    SelfLinks:
      type: object
      description: A links object containing the self link.
      readOnly: true
      properties:
        self:
          $ref: '#/components/schemas/Link'
    AccountGroupId:
      type: string
      description: A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint.
      example: '1234'
  responses:
    '429':
      description: Exhausted rate limit for the organization
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: about:blank
            title: URI Resource Not Found
            status: 404
            detail: Details explaining if the 404 error is related to an invalid URI or a wrong ID
            instance: /v7
    '500':
      description: Internal server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: about:blank
            title: Internal server error
            status: 500
            detail: Optional detail about the internal error message.
            instance: /v7
    '400':
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            type: about:blank
            title: Request validation failed. There are invalid or missing fields
            status: 400
            detail: Your request object contains invalid fields.
            instance: /v7
            errors:
            - code: AM-5432
              field: firstName
              message: firstName cannot have fancy characters
            - code: DASH-5622
              field: password
              message: Password cannot be blank
    '403':
      description: Insufficient permissions to query endpoint
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    '204':
      description: No content
  parameters:
    UserIdPath:
      name: id
      description: Identifier for the user.
      required: true
      in: path
      schema:
        type: string
        example: '1234'
    AccountGroupId:
      name: aid
      in: query
      description: A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that you must be assigned to the target account group. Specifying this parameter without being assigned to the target account group will result in an error response.
      required: false
      schema:
        type: string
        example: '1234'
  headers:
    Location:
      schema:
        type: string
        format: uri
        example: https://api.thousandeyes.com/v7/link/to/resource/id
      description: The absolute path to created resource.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
externalDocs:
  description: Find out more about the administrative models
  url: https://docs.thousandeyes.com/product-documentation/user-management