Select the tab
ESET Connect – Table of Contents

POST Assign role

Relative path: /v2/role-assignments:assignRole

Assign a role to a subject. Eventually, the subject ends with its existing roles and those assigned by this operation.

For example:
"User X" is an "admin" of the Subscription B.
AssignRole( "User X", { "admin", ["Subscription A", "Subscription C"])
leaves the user being an admin of the Subscriptions A, B, and C.

Base URL for Europe, Germany, United States, Canada and Japan regions:






Request body

Display Schema instead of an Example or vice-versa

Type

Required

Example

Schema

application/json

Yes

{
  "role": {
    "roleName": "string",
    "scopes": [
      {
        "assetGroupUuid": "string",
        "customerUuid": "string",
        "deviceUuid": "string",
        "mspUuid": "string",
        "policyUuid": "string",
        "siteUuid": "string",
        "subscriptionUuid": "string",
        "userUuid": "string",
        "tenantUuid": "string"
      }
    ]
  },
  "subjectReference": "string",
  "subjectType": "SUBJECT_TYPE_UNSPECIFIED"
}
{
  "$ref": "v2AssignRoleRequest",
  "role": {
    "$ref": "v2ScopedRole",
    "description": "Combines the [role] and [scope]s. Roles might have effects limited by the scopes. For example, a user might be an admin of a specific device. Info: On the Internet the concept of the scope (for example, Scope) can be found under different names: Condition from: REST Resource: roleAssignments Context from: Term Definition: Contextual Role",
    "roleName": {
      "type": "string",
      "description": "The role name is the identifier of the Role. For example, 'admin', or 'security.viewer', or '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1' Roles are referenced by their names."
    },
    "scopes": [
      {
        "$ref": "v2Scope",
        "description": "[Scope] for a role assignment. Scope narrows down the application of a role. [Scope]s can be hierarchical, which implies role inheritance. Info: On the Internet the concept of the scope (for example, Scope) can be found under different names: Condition from: REST Resource: roleAssignments Context from: Term Definition: Contextual Role",
        "assetGroupUuid": {
          "type": "string",
          "description": "Scope of the referenced [group] from asset management. type: asset_management.v1.Group"
        },
        "customerUuid": {
          "type": "string",
          "description": "Scope of the referenced [customer]. Info: The [customer] scope is covered by the more abstract [tenant] scope, which will eventually be used instead of the [customer] scope. type: customer_management.v2.Customer"
        },
        "deviceUuid": {
          "type": "string",
          "description": "Scope of the referenced [device]. type: device_management.v1.Device"
        },
        "mspUuid": {
          "type": "string",
          "description": "Scope of the referenced [MSP]. Info: The [MSP] scope is covered by the more abstract [tenant] scope, which will eventually be used instead of the [customer] scope. type: msp_management.v1.Msp"
        },
        "policyUuid": {
          "type": "string",
          "description": "Scope of the referenced [policy]. type: policy_management.v1.Policy"
        },
        "siteUuid": {
          "type": "string",
          "description": "[Site] reference. type: organization_site_management.v1.Site"
        },
        "subscriptionUuid": {
          "type": "string",
          "description": "Scope of the referenced [subscription]. type: subscription_management.v1.Subscription"
        },
        "userUuid": {
          "type": "string",
          "description": "Scope of the referenced [user]. type: user_management.v1.User"
        },
        "tenantUuid": {
          "type": "string",
          "description": "Tenant typically represents an organization unit recognized by ESET. Tenant defines the logical scope of the managed entities. Each managed entity is owned by exactly one tenant, which means its life cycle is inherently dependent on the tenant’s life cycle. type: tenant_management.v1.Tenant"
        }
      }
    ]
  },
  "subjectReference": {
    "type": "string",
    "description": "Reference to the [user], [device] or whatever identifies the subject."
  },
  "subjectType": {
    "$ref": "v2SubjectType",
    "type": "string",
    "description": "The type of principal represented by the subject to whom the roles are assigned. SUBJECT_TYPE_UNSPECIFIED: fallback SUBJECT_TYPE_USER: Subject represents a [user]. SUBJECT_TYPE_DEVICE: Subject represents a [device]. SUBJECT_TYPE_USER_GROUP: Roles can be assigned to a user group. Then, the roles are inferred from the groups of the authenticated user. - SUBJECT_TYPE_MANAGED_IDENTITY: The subject has a managed identity. Managed identities are used by the API clients to access services.",
    "default": "SUBJECT_TYPE_UNSPECIFIED",
    "enum": [
      "SUBJECT_TYPE_UNSPECIFIED",
      "SUBJECT_TYPE_USER",
      "SUBJECT_TYPE_DEVICE",
      "SUBJECT_TYPE_USER_GROUP",
      "SUBJECT_TYPE_MANAGED_IDENTITY"
    ]
  }
}


Responses

Display Schema+Headers instead of an Example or vice-versa

Code

Description and Example

Description, Schema and Headers

200

Successful response.

Successful response.


Response schema

{
  "$ref": "v2AssignRoleResponse",
  "title": "empty",
  "type": "object"
}


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

202

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

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


Response schema

[]


Headers

{
  "response-id": {
    "description": "Unique ID of a pending request. Used to retrieve cached result.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

400

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

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


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

401

Token has expired or is invalid.

Token has expired or is invalid.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

403

Access denied. Check permissions.

Access denied. Check permissions.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

404

Requested resource not found.

Requested resource not found.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

429

Rate limit reached. Try again later.

Rate limit reached. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

500

Internal server failure. Try again later.

Internal server failure. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

502

Internal server failure. Try again later.

Internal server failure. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

503

Environment under maintenance. Try again later.

Environment under maintenance. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

504

Action took too long; timeout reached

Action took too long; timeout reached


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}