Select the tab
ESET Connect – Table of Contents

GET List users

Relative path: /v1/users

Retrieves a list of users, optionally filtered by certain criteria, defined in user filter.

Query parameters

Name

Type

Description

activeProduct.autoActivated

boolean

If true, the product was activated automatically. That is the product was activated because it is automatically activated for all the users within of some user-group or user's tenant.

activeProduct.autoActivationDetails.base

string

Base, on which the product has been automatically activated for the user.

For example, some products are activated based on the automation at the level of user's tenant.

PRODUCT_AUTO_ACTIVATION_BASE_UNSPECIFIED: fallback

PRODUCT_AUTO_ACTIVATION_BASE_TENANT: Product is activated for this user because automatic activation was enabled on user's tenant.

PRODUCT_AUTO_ACTIVATION_BASE_USER_GROUP: Product is activated for this user because automatic activation was enabled on some of the user's groups.

activeProduct.autoActivationDetails.userGroupUuid

string

Reference to [user group].

Only meaningful if the base is equal to USER GROUP.

type: UserGroup

activeProduct.subscriptionUuid

string

Reference to [subscription], used for product activation.

type: subscription_management.v1.Subscription

activeProduct.unitPoolUuid

string

Reference to [unit pool], used for product activation.

Unit pools contain units available for product activation.

type: unit_management.v1.UnitPool

activeProduct.id

integer

Identifier of governed resource. Can be seen as a value of item in enumerated type.

It can be derived from name by some algorithm such as CRC32.

activeProduct.name

string

Name of the governed item. Can be seen as a name of enumeration item, with id being its numerical value.

Note: Not to be confused with display_name, which is purposed for UI.

cloudOfficeTenantReference

string

Filtering based on user's cloud office tenant reference.

If filled, only the users of given cloud office tenant reference will be included in the response. Exact match is required.

If null or empty, users of any or none cloud office tenant will be included in the response.

displayName

string

Filtering based on user's display name.

If filled, only the users containing given display name (at least partially) will be included in the response.

If null or empty, users from any display name will be included in the response.

email

string

Filtering based on user email.

If filled, only the users containing given email (at least partially) within primary email address or proxy email addresses will be included in the response.

If null or empty, users with any email address will be included in the response.

hasCloudOfficeMsLicense

boolean

If true, include only users with associated Microsoft (MS) cloud office license.

If false, include only users without associated Microsoft (MS) cloud office license.

If null, this filter does not apply at all.

protectionStatus

string

Filtering based on user's protection status.

If not-null or non-zero, only the users with given protection status will be included in the response. Users with any protection status will be returned otherwise.

PROTECTION_STATUS_UNSPECIFIED: fallback

PROTECTION_STATUS_UNPROTECTED: Status where selected asset is not protected by enabled ESET protection features.

PROTECTION_STATUS_PENDING: Status where asset is not protected by enabled protection features yet, the protection is in pending state. The protection features are setting up.

PROTECTION_STATUS_PARTIALLY_PROTECTED: Status where asset is protected by enabled protection features, with some complications, that require the attention.

PROTECTION_STATUS_FULLY_PROTECTED: Status where asset is fully protected by enabled ESET protection features.

userGroupUuid

string

Filtering based on user group.

If null or empty, users from any user group will be included in the response.

type: UserGroup

pageSize

integer

Limit for pagination purposes.

If unspecified or 0, default value is 50. The maximum value is 1000; values above 1000 will be coerced to 1000.

Info: For more information, refer to Paginating Requests in APIs

or https://cloud.google.com/apis/design/design_patterns#list_pagination

pageToken

string

Page token of current page.

If not given or "", the first page is returned.

Info: For more information, refer to Paginating Requests in APIs

or https://cloud.google.com/apis/design/design_patterns#list_pagination



Responses

Display Schema instead of an Example or vice-versa

Code

Description

Example

Schema

200

Successful response.

{
  "users": [
    {
      "activeProductIds": [
        0
      ],
      "cloudOffice": {
        "hasMsLicense": true,
        "tenantReference": "string"
      },
      "department": "string",
      "displayName": "string",
      "identities": [
        {
          "createTime": "string",
          "providerReference": "string",
          "providerReferenceFormat": "IDENTITY_REFERENCE_FORMAT_UNSPECIFIED",
          "providerType": "IDENTITY_PROVIDER_TYPE_UNSPECIFIED",
          "updateTime": "string",
          "userName": "string"
        }
      ],
      "jobTitle": "string",
      "officeLocation": "string",
      "phoneNumbers": [
        "string"
      ],
      "primaryEmailAddress": "string",
      "protectionStatus": "PROTECTION_STATUS_UNSPECIFIED",
      "proxyEmailAddresses": [
        "string"
      ],
      "userGroupUuids": [
        "string"
      ],
      "uuid": "string"
    }
  ],
  "nextPageToken": "string",
  "totalSize": 0
}
{
  "$ref": "v1ListUsersResponse",
  "users": [
    {
      "$ref": "v1User",
      "description": "Representation of physical user. Every user can have multiple identities and multiple accounts. Account is user's representation in some system, whereas identity is.",
      "activeProductIds": [
        {
          "type": "integer",
          "format": "int64"
        }
      ],
      "cloudOffice": {
        "$ref": "v1CloudOfficeUser",
        "description": "Details of user related to their cloud office (e.g. Microsoft Office 365 or Google Workspace) origin.",
        "hasMsLicense": {
          "type": "boolean",
          "description": "For an user imported from Microsoft Office 365, true if the user has assigned Microsoft licenses. Info: Projection of assigned licenses from Graph API."
        },
        "tenantReference": {
          "type": "string",
          "description": "Reference to cloud office tenant from where the user originates. The format might differ in dependence on the origin (e.g. Microsoft Office 365 uses predominantly UUID, whereas Google Workspace uses random string)."
        }
      },
      "department": {
        "type": "string",
        "description": "The department to which the user belongs. Can be used for organizational categorization and role-based access control."
      },
      "displayName": {
        "type": "string",
        "description": "The name of user displayed in address books. Usually, it is a full name, a combination of first name, middle and last names. Validation: - required - max length 255 Example: John Doe"
      },
      "identities": [
        {
          "$ref": "v1Identity",
          "description": "Represents an identity used to sign in to a user account. Each user can have multiple identities, such as Active Directory (AD), internet service provider (ISP) identity, or identities provided by Google, Facebook, or Microsoft, and so on. These identities enable user to sign in to the user accounts. It helps manage and track these different identities, ensuring seamless authentication and authorization across various platforms and services. Identity is managed by Identity Provider where the identity can also be verified (i.e. authenticated).",
          "createTime": {
            "type": "string",
            "description": "Date and time when the identity was created. Empty if the timestamp is unknown.",
            "format": "date-time"
          },
          "providerReference": {
            "type": "string",
            "description": "The identifier used by the identity provider for the user. example: user123@company.com"
          },
          "providerReferenceFormat": {
            "$ref": "v1IdentityReferenceFormat",
            "type": "string",
            "description": "Possible formats of user references. IDENTITY_REFERENCE_FORMAT_UNSPECIFIED: fallback IDENTITY_REFERENCE_FORMAT_EMAIL_ADDRES: User identity reference (login) is an email address. IDENTITY_REFERENCE_FORMAT_USER_NAME: User identity reference (login) is an username. IDENTITY_REFERENCE_FORMAT_USER_PRINCIPAL_NAME: User identity reference (login) is in Universal principal name (UPN) format. IDENTITY_REFERENCE_FORMAT_PHONE_NUMBER: User identity reference (login) is a telephone number. IDENTITY_REFERENCE_FORMAT_FEDERATED: An unique identifier for a user from an provider that can be in any format chosen by the provider.",
            "default": "IDENTITY_REFERENCE_FORMAT_UNSPECIFIED",
            "enum": [
              "IDENTITY_REFERENCE_FORMAT_UNSPECIFIED",
              "IDENTITY_REFERENCE_FORMAT_EMAIL_ADDRES",
              "IDENTITY_REFERENCE_FORMAT_USER_NAME",
              "IDENTITY_REFERENCE_FORMAT_USER_PRINCIPAL_NAME",
              "IDENTITY_REFERENCE_FORMAT_PHONE_NUMBER",
              "IDENTITY_REFERENCE_FORMAT_FEDERATED"
            ]
          },
          "providerType": {
            "$ref": "v1IdentityProviderType",
            "title": "Identity providers that can be used for authentication",
            "type": "string",
            "description": "IDENTITY_PROVIDER_TYPE_UNSPECIFIED: fallback IDENTITY_PROVIDER_TYPE_MICROSOFT: Represents Microsoft Entra ID (former Azure Active Directory, or Azure AD) as an identity provider for enterprise authentication. IDENTITY_PROVIDER_TYPE_GOOGLE: Represents Google as an identity provider for authentication via Google accounts. IDENTITY_PROVIDER_TYPE_FACEBOOK: Represents Facebook as an identity provider for authentication via Facebook accounts. IDENTITY_PROVIDER_TYPE_LOCAL: Represents a local provider that manages identities and authentication within the application's scope.",
            "default": "IDENTITY_PROVIDER_TYPE_UNSPECIFIED",
            "enum": [
              "IDENTITY_PROVIDER_TYPE_UNSPECIFIED",
              "IDENTITY_PROVIDER_TYPE_MICROSOFT",
              "IDENTITY_PROVIDER_TYPE_GOOGLE",
              "IDENTITY_PROVIDER_TYPE_FACEBOOK",
              "IDENTITY_PROVIDER_TYPE_LOCAL"
            ]
          },
          "updateTime": {
            "type": "string",
            "description": "Date and time when the identity was last updated. Empty if the timestamp is unknown.",
            "format": "date-time"
          },
          "userName": {
            "type": "string",
            "description": "User name as a form of identity reference. Derived from provider reference if the provider reference format is suitable. Examples: - system\user - name.surname - login@somedomain.com Info: Inspired by: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/sssd-user-ids"
          }
        }
      ],
      "jobTitle": {
        "type": "string",
        "description": "The job title of a user, representing their specific role or position within an organization or context. This attribute defines the user's job function and helps identify their responsibilities and role within the system."
      },
      "officeLocation": {
        "type": "string",
        "description": "The physical office location or workplace of a user, representing the physical location or environment where the user is typically working or sitting while using the system. This can include an office, remote work location, or any other place relevant to the user's work activities."
      },
      "phoneNumbers": [
        {
          "type": "string"
        }
      ],
      "primaryEmailAddress": {
        "type": "string",
        "description": "The SMTP address for the user, for example, jeff@contoso.com. Changes to this property update the user's proxyAddresses collection to include the value as an SMTP address. This property can't contain accent characters. Validation: - valid email address format - max length 255 Example: john.doe@example.com"
      },
      "protectionStatus": {
        "$ref": "v1ProtectionStatus",
        "type": "string",
        "description": "Aggregated status of protection, per context of specific asset. PROTECTION_STATUS_UNSPECIFIED: fallback PROTECTION_STATUS_UNPROTECTED: Status where selected asset is not protected by enabled ESET protection features. PROTECTION_STATUS_PENDING: Status where asset is not protected by enabled protection features yet, the protection is in pending state. The protection features are setting up. PROTECTION_STATUS_PARTIALLY_PROTECTED: Status where asset is protected by enabled protection features, with some complications, that require the attention. PROTECTION_STATUS_FULLY_PROTECTED: Status where asset is fully protected by enabled ESET protection features.",
        "default": "PROTECTION_STATUS_UNSPECIFIED",
        "enum": [
          "PROTECTION_STATUS_UNSPECIFIED",
          "PROTECTION_STATUS_UNPROTECTED",
          "PROTECTION_STATUS_PENDING",
          "PROTECTION_STATUS_PARTIALLY_PROTECTED",
          "PROTECTION_STATUS_FULLY_PROTECTED"
        ]
      },
      "proxyEmailAddresses": [
        {
          "type": "string"
        }
      ],
      "userGroupUuids": [
        {
          "type": "string"
        }
      ],
      "uuid": {
        "type": "string",
        "description": "Unique identifier of the entity. Must be collision free - two identifiers created anywhere in the world must not collide within entity parent scope. Unless a member of aggregate, the entity scope is always global. Although most of the times compliant with RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace, do not rely on it being a RFC UUID. Treat it as an opaque identifier. RFC UUID can be recognized by being formatted according to template xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx, as explained on wikipedia. UUID is used for referencing an entity, even across domains. Example: '123e4567-e89b-12d3-a456-426614174000'"
      }
    }
  ],
  "nextPageToken": {
    "type": "string",
    "description": "Page token of next page. Empty or '' for the last page. Info: For more information, refer to Paginating Requests in APIs or https://cloud.google.com/apis/design/design_patterns#list_pagination"
  },
  "totalSize": {
    "type": "integer",
    "description": "The total count of items in the list irrespective of pagination. Info: One of the standard fields Page_size might differ for every call (it is an input parameter) so the calculation of how many pages there is in total is caller's responsibility.",
    "format": "int64"
  }
}

202

Response took too long; request cached. Response can be retrieved later using the response-id header.

null
[]

400

One of the errors: 1. Bad or missing authorization. 2. Validation error. Invalid argument provided.

null
[]

401

Token has expired or is invalid.

null
[]

403

Access denied. Check permissions.

null
[]

404

Requested resource not found.

null
[]

429

Rate limit reached. Try again later.

null
[]

500

Internal server failure. Try again later.

null
[]

502

Internal server failure. Try again later.

null
[]

503

Environment under maintenance. Try again later.

null
[]

504

Action took too long; timeout reached

null
[]