Warning: The Notifications API is deprecated and will be shutdown soon.

Managing Roles

The Directory API lets you use role-based access control to manage user access to features in your domain. You do this by managing privileges and roles and their assignment to users.

Overview

A privilege is necessary to perform certain tasks and operations in a domain. A role is a collection of privileges (of possibly different services like the Users service, Chrome, and so on) that grants users with that role the ability to perform certain tasks or operations. A role assignment is a record of a particular role given to a user.

The methods in this guide can be used to create roles and manage role assignments for users in a domain. The general process involves using the following three resources:

  • The privileges resource is used to get a list of supported privileges in the domain.
  • The roles resource is used to create new roles or get existing roles.
  • The roleAssignments resource is used to assign a role to a user in the domain.

Get supported privileges

To get a list of supported privileges, use the following GET request and include the authorization described in Authorize requests.

  • If you are an administrator getting privileges in your own domain, use my_customer as the customer ID.

  • If you are reseller getting privileges for one of your customers, use the customer ID returned by the Retrieve a user operation.

Request

GET https://www.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the privileges supported in the domain:

{
  "kind": "admin\#directory\#privileges",
  "etag": ...,
  "items": [
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "02afmg282jiquyg",
      "privilegeName": "APP_ADMIN",
      "isOuScopable": false
    },
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "04f1mdlm0ki64aw",
      "privilegeName": "MANAGE_USER_SETTINGS",
      "isOuScopable": true,
      "childPrivileges": [
        {
          "kind": "admin\#directory\#privilege",
          "etag": ...,
          "serviceId": "04f1mdlm0ki64aw",
          "privilegeName": "MANAGE_APPLICATION_SETTINGS",
          "isOuScopable": true
        }
      ]
    },
    ...
  ]
}

Get existing roles

To get a list of existing roles, use the following GET request and include the authorization described in Authorize requests.

  • If you are an administrator getting roles in your own domain, use my_customer as the customer ID.

If you are reseller getting roles for a customer, use the customer ID that you got using the Retrieve a user operation.

Request

GET https://www.googleapis.com/admin/directory/v1/customer/customer_id/roles

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the roles that exist in the domain:

{
  "kind": "admin\#directory\#roles",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
  "items": [
    {
      "kind": "admin\#directory\#role",
      "etag": ... ,
      "roleId": "3894208461012993",
      "roleName": "_SEED_ADMIN_ROLE",
      "roleDescription": "G Suite Administrator Seed Role",
      "rolePrivileges": [
        {
          "privilegeName": "SUPER_ADMIN",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ROOT_APP_ADMIN",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_APIS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        ...
      ],
      "isSystemRole": true,
      "isSuperAdminRole": true
    },
    {
      "kind": "admin\#directory\#role",
      "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
      "roleId": "3894208461012994",
      "roleName": "_GROUPS_ADMIN_ROLE",
      "roleDescription": "Groups Administrator",
      "rolePrivileges": [
        {
          "privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "USERS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "GROUPS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_DASHBOARD",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        }
      ],
      "isSystemRole": true
    },
    ...
  ]
}

Create a role

To create a new role, use the following POST request and include the authorization described in Authorize requests. Add a privilegeName and serviceId for each privilege that should be granted with this role. For the request and response properties, see the API Reference:

Request

POST https://www.googleapis.com/admin/directory/v1/customer/customer_id/roles

{
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

Response

A successful response returns an HTTP 201 status code. Along with the status code, the response returns the properties for the new role:

{
  "kind": "admin\#directory\#role",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
  "roleId": "3894208461013031",
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

Create a role assignment

To assign a role to a user, use the following POST method and include the authorization described in Authorize requests. Add a JSON body with the user_id of the user, which you can get from users.get(), and the roleId as described in Get existing roles.

Request

POST https://www.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Response

A successful response returns an HTTP 201 status code. Along with the status code, the response returns the properties for the new role assignment:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Assign Admin Console UI roles

To assign roles for users that will access their privileges through the Admin Console UI, certain extra privileges may need to be granted. For example, to grant a user the ability to create other users through the Admin Console UI, not only is the USERS_CREATE privilege required but also the USERS_UPDATE and ORGANIZATION_UNITS_RETRIEVE privileges. The following table is an exhaustive list mapping the Admin Console UI functionality to the corresponding required privilege grants.

Admin Console UI Functionality Privileges Needed
Organizational Units - Read ORGANIZATION_UNITS_RETRIEVE
Organizational Units - Create ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
Organizational Units - Update ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
Organizational Units - Delete ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
Organizational Units ORGANIZATION_UNITS_ALL
Users - Read USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Create USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Users - Update USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Users - Move Users USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Rename Users USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Reset Password USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Force Password Change USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Add/Remove Aliases USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Suspend Users USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
GROUPS GROUPS_ALL
Security - User Security Management USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE