Manage users, groups, organizational units, and devices in a Google Workspace domain.
openapi: 3.1.0
info:
title: Google Workspace Admin SDK Directory API
description: >-
Manage users, groups, and organizational units in a Google Workspace domain.
The Admin SDK Directory API lets administrators of enterprise domains view
and manage resources such as user accounts, groups, and organizational units
within their Google Workspace domain.
version: directory_v1
contact:
name: Google Workspace Developer Support
url: https://developers.google.com/admin-sdk/directory
license:
name: Google APIs Terms of Service
url: https://developers.google.com/terms
x-logo:
url: https://www.gstatic.com/images/branding/product/2x/admin_2020q4_48dp.png
externalDocs:
description: Google Admin SDK Directory API Documentation
url: https://developers.google.com/admin-sdk/directory/reference/rest
servers:
- url: https://admin.googleapis.com
description: Google Admin SDK production endpoint
security:
- oauth2: []
tags:
- name: Users
description: Manage user accounts in a Google Workspace domain
externalDocs:
url: https://developers.google.com/admin-sdk/directory/reference/rest/v1/users
- name: Groups
description: Manage groups in a Google Workspace domain
externalDocs:
url: https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups
- name: OrgUnits
description: Manage organizational units in a Google Workspace domain
externalDocs:
url: https://developers.google.com/admin-sdk/directory/reference/rest/v1/orgunits
paths:
# ──────────────────────────────────────────────
# Users
# ──────────────────────────────────────────────
/admin/directory/v1/users:
get:
operationId: listUsers
summary: List Users
description: >-
Retrieves a paginated list of either deleted users or all users in a
domain. Requires authorization with the
admin.directory.user.readonly or admin.directory.user scope.
tags:
- Users
parameters:
- $ref: '#/components/parameters/domain'
- $ref: '#/components/parameters/customer'
- name: maxResults
in: query
description: Maximum number of results to return (1-500). Default is 100.
schema:
type: integer
minimum: 1
maximum: 500
default: 100
- name: pageToken
in: query
description: Token to specify the next page in the list.
schema:
type: string
- name: orderBy
in: query
description: Property to use for sorting results.
schema:
type: string
enum:
- email
- familyName
- givenName
- name: sortOrder
in: query
description: Whether to return results in ascending or descending order.
schema:
type: string
enum:
- ASCENDING
- DESCENDING
- name: query
in: query
description: >-
Query string for searching user fields. For more information on
constructing user queries, see the Search for Users documentation.
schema:
type: string
- name: showDeleted
in: query
description: If set to true, retrieves the list of deleted users.
schema:
type: string
- name: projection
in: query
description: What subset of fields to fetch for this user.
schema:
type: string
enum:
- basic
- custom
- full
- name: viewType
in: query
description: >-
Whether to fetch the administrator-only or domain-wide public view
of the user. Default is admin_view.
schema:
type: string
enum:
- admin_view
- domain_public
- name: customFieldMask
in: query
description: >-
A comma-separated list of schema names. All fields from these
schemas are fetched. Must be set when projection=custom.
schema:
type: string
responses:
'200':
description: Successful response containing a list of users.
content:
application/json:
schema:
$ref: '#/components/schemas/Users'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: insertUser
summary: Create a User
description: >-
Creates a user account. The new user account is created in the
customer account specified in the request body.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'200':
description: Successfully created user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: User already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/users/{userKey}:
parameters:
- $ref: '#/components/parameters/userKey'
get:
operationId: getUser
summary: Get a User
description: >-
Retrieves a user account by user key (primary email address, alias
email address, or unique user ID).
tags:
- Users
parameters:
- name: projection
in: query
description: What subset of fields to fetch for this user.
schema:
type: string
enum:
- basic
- custom
- full
- name: viewType
in: query
description: >-
Whether to fetch the administrator-only or domain-wide public view
of the user.
schema:
type: string
enum:
- admin_view
- domain_public
- name: customFieldMask
in: query
description: >-
A comma-separated list of schema names. All fields from these
schemas are fetched. Must be set when projection=custom.
schema:
type: string
responses:
'200':
description: Successful response containing the user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateUser
summary: Update a User
description: >-
Updates a user account. This replaces the entire user resource.
Use patch for partial updates.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'200':
description: Successfully updated user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: patchUser
summary: Patch a User
description: >-
Updates a user account using patch semantics. Only the fields
specified in the request body are updated.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'200':
description: Successfully patched user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteUser
summary: Delete a User
description: >-
Deletes a user account. Deleted users are recoverable for a
period of 20 days using the undelete method.
tags:
- Users
responses:
'204':
description: Successfully deleted user. No content returned.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/users/{userKey}/makeAdmin:
post:
operationId: makeUserAdmin
summary: Make a User a Super Administrator
description: >-
Makes a user a super administrator. This can only be done by another
super administrator.
tags:
- Users
parameters:
- $ref: '#/components/parameters/userKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
type: boolean
description: >-
Indicates the administrator status of the user. True
grants super administrator privileges.
responses:
'204':
description: Successfully updated admin status.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/users/{userKey}/undelete:
post:
operationId: undeleteUser
summary: Undelete a User
description: >-
Restores a recently deleted user account. Users are recoverable for
a period of 20 days after deletion.
tags:
- Users
parameters:
- $ref: '#/components/parameters/userKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
orgUnitPath:
type: string
description: >-
The full path of the parent organization unit to place
the undeleted user into.
responses:
'204':
description: Successfully undeleted user.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/users/{userKey}/signOut:
post:
operationId: signOutUser
summary: Sign Out a User
description: >-
Signs a user out of all web and device sessions and resets their
sign-in cookies.
tags:
- Users
parameters:
- $ref: '#/components/parameters/userKey'
responses:
'204':
description: Successfully signed out user.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
# ──────────────────────────────────────────────
# Groups
# ──────────────────────────────────────────────
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/groups:
get:
operationId: listGroups
summary: List Groups
description: >-
Retrieves all groups of a domain or all groups a user is a member
of. Requires authorization with the admin.directory.group.readonly
or admin.directory.group scope.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/domain'
- $ref: '#/components/parameters/customer'
- name: maxResults
in: query
description: Maximum number of results to return (1-200). Default is 200.
schema:
type: integer
minimum: 1
maximum: 200
default: 200
- name: pageToken
in: query
description: Token to specify the next page in the list.
schema:
type: string
- name: orderBy
in: query
description: Column to use for sorting results.
schema:
type: string
enum:
- email
- name: sortOrder
in: query
description: Whether to return results in ascending or descending order.
schema:
type: string
enum:
- ASCENDING
- DESCENDING
- name: userKey
in: query
description: >-
Email or immutable ID of the user to list groups for. If specified,
returns only those groups the user is a member of.
schema:
type: string
- name: query
in: query
description: >-
Query string for searching group fields. See the Searching for
Groups documentation for supported fields.
schema:
type: string
responses:
'200':
description: Successful response containing a list of groups.
content:
application/json:
schema:
$ref: '#/components/schemas/Groups'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: insertGroup
summary: Create a Group
description: Creates a group in the specified domain.
tags:
- Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
responses:
'200':
description: Successfully created group.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: Group already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/groups/{groupKey}:
parameters:
- $ref: '#/components/parameters/groupKey'
get:
operationId: getGroup
summary: Get a Group
description: >-
Retrieves a group's properties by group key (group email address,
group alias, or the unique group ID).
tags:
- Groups
responses:
'200':
description: Successful response containing the group.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateGroup
summary: Update a Group
description: Updates a group's properties. This replaces the entire group resource.
tags:
- Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
responses:
'200':
description: Successfully updated group.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: patchGroup
summary: Patch a Group
description: >-
Updates a group's properties using patch semantics. Only the
specified fields are updated.
tags:
- Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
responses:
'200':
description: Successfully patched group.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteGroup
summary: Delete a Group
description: Deletes a group.
tags:
- Groups
responses:
'204':
description: Successfully deleted group. No content returned.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
# ──────────────────────────────────────────────
# OrgUnits
# ──────────────────────────────────────────────
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/customer/{customerId}/orgunits:
parameters:
- $ref: '#/components/parameters/customerId'
get:
operationId: listOrgUnits
summary: List Organizational Units
description: >-
Retrieves a list of all organizational units for an account.
The hierarchy of organizational units is limited to 35 levels of
depth.
tags:
- OrgUnits
parameters:
- name: type
in: query
description: >-
Whether to return all sub-organizations or just immediate children.
schema:
type: string
enum:
- all
- children
- allIncludingParent
- name: orgUnitPath
in: query
description: >-
The full path to the organizational unit or its unique ID. Returns
child organizational units beneath the specified path.
schema:
type: string
responses:
'200':
description: Successful response containing a list of organizational units.
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnits'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: insertOrgUnit
summary: Create an Organizational Unit
description: Adds an organizational unit under the specified customer account.
tags:
- OrgUnits
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnit'
responses:
'200':
description: Successfully created organizational unit.
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnit'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/directory/v1/customer/{customerId}/orgunits/{orgUnitPath}:
parameters:
- $ref: '#/components/parameters/customerId'
- $ref: '#/components/parameters/orgUnitPath'
get:
operationId: getOrgUnit
summary: Get an Organizational Unit
description: Retrieves an organizational unit.
tags:
- OrgUnits
responses:
'200':
description: Successful response containing the organizational unit.
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnit'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateOrgUnit
summary: Update an Organizational Unit
description: >-
Updates an organizational unit. This replaces the entire resource.
Use patch for partial updates.
tags:
- OrgUnits
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnit'
responses:
'200':
description: Successfully updated organizational unit.
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnit'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: patchOrgUnit
summary: Patch an Organizational Unit
description: >-
Updates an organizational unit using patch semantics. Only the
specified fields are updated.
tags:
- OrgUnits
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnit'
responses:
'200':
description: Successfully patched organizational unit.
content:
application/json:
schema:
$ref: '#/components/schemas/OrgUnit'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteOrgUnit
summary: Delete an Organizational Unit
description: >-
Removes an organizational unit. Only empty organizational units
can be deleted. All users and child organizational units must be
moved or deleted before the parent can be removed.
tags:
- OrgUnits
responses:
'204':
description: Successfully deleted organizational unit. No content returned.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
# ──────────────────────────────────────────────
# Security Schemes
# ──────────────────────────────────────────────
securitySchemes:
oauth2:
type: oauth2
description: OAuth 2.0 authorization for Google Workspace Admin operations.
flows:
authorizationCode:
authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
tokenUrl: https://oauth2.googleapis.com/token
refreshUrl: https://oauth2.googleapis.com/token
scopes:
https://www.googleapis.com/auth/admin.directory.user: View and manage the provisioning of users on your domain
https://www.googleapis.com/auth/admin.directory.user.readonly: View users on your domain
https://www.googleapis.com/auth/admin.directory.group: View and manage the provisioning of groups on your domain
https://www.googleapis.com/auth/admin.directory.group.readonly: View groups on your domain
https://www.googleapis.com/auth/admin.directory.orgunit: View and manage organization units on your domain
https://www.googleapis.com/auth/admin.directory.orgunit.readonly: View organization units on your domain
# ──────────────────────────────────────────────
# Parameters
# ──────────────────────────────────────────────
parameters:
userKey:
name: userKey
in: path
required: true
description: >-
Identifies the user in the API request. The value can be the user
primary email address, alias email address, or unique user ID.
schema:
type: string
groupKey:
name: groupKey
in: path
required: true
description: >-
Identifies the group in the API request. The value can be the group
email address, group alias, or the unique group ID.
schema:
type: string
customerId:
name: customerId
in: path
required: true
description: >-
The unique ID for the customer Google Workspace account. Use the
value my_customer to represent the account associated with the
authenticated administrator.
schema:
type: string
orgUnitPath:
name: orgUnitPath
in: path
required: true
description: >-
The full path of the organizational unit (minus the leading /) or
its unique ID.
schema:
type: string
domain:
name: domain
in: query
description: >-
The domain name. Use this field to get groups from only one domain.
To return all domains for a customer account, use the customer
query parameter instead.
schema:
type: string
customer:
name: customer
in: query
description: >-
The unique ID for the customer Google Workspace account. In a
multi-domain account, use this to list all groups for a customer.
You can also use the my_customer alias.
schema:
type: string
# ──────────────────────────────────────────────
# Schemas
# ──────────────────────────────────────────────
schemas:
User:
type: object
description: >-
A Google Workspace user account. JSON representation of a user
resource from the Admin SDK Directory API.
properties:
kind:
type: string
description: The type of the API resource.
default: admin#directory#user
readOnly: true
example: example_value
id:
type: string
description: The unique ID for the user.
readOnly: true
example: abc123
etag:
type: string
description: ETag of the resource.
readOnly: true
example: example_value
primaryEmail:
type: string
format: email
description: >-
The user primary email address. This property is required in a
request to create a user account. The primaryEmail must be unique
and cannot be an alias of another user.
example: [email protected]
name:
$ref: '#/components/schemas/UserName'
isAdmin:
type: boolean
description: >-
Indicates a user with super administrator privileges. The isAdmin
property can only be edited using the makeAdmin method; it is not
directly editable in the user resource.
readOnly: true
example: true
isDelegatedAdmin:
type: boolean
description: Indicates if the user is a delegated administrator.
readOnly: true
example: true
lastLoginTime:
type: string
format: date-time
description: >-
The last time the user logged into the user account. The value
is in ISO 8601 date and time format.
readOnly: true
example: '2026-01-15T10:30:00Z'
creationTime:
type: string
format: date-time
description: >-
The time the user account was created. The value is in ISO 8601
date and time format.
readOnly: true
example: '2026-01-15T10:30:00Z'
deletionTime:
type: string
format: date-time
description: The time the user account was deleted (for deleted users).
readOnly: true
example: '2026-01-15T10:30:00Z'
agreedToTerms:
type: boolean
description: >-
Indicates whether the user has completed an initial login and
accepted the Terms of Service.
readOnly: true
example: true
password:
type: string
description: >-
Stores the password for the user account. The password value is
never returned in the API response body. Required when creating
a user account. Must be 8-100 ASCII characters.
writeOnly: true
example: example_value
hashFunction:
type: string
description: >-
Stores the hash format of the password property. Use MD5,
SHA-1, or crypt for supported hash formats.
enum:
- MD5
- SHA-1
- crypt
example: MD5
suspended:
type: boolean
description: >-
Indicates if the user is suspended. A suspended user cannot
sign in.
example: true
suspensionReason:
type: string
description: >-
The reason a user account is suspended. Only returned
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google-workspace/refs/heads/main/openapi/admin-sdk-directory-api.yml