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: user@example.com
        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 when the
            suspended property is true.
          readOnly: true
          example: example_value
        changePasswordAtNextLogin:
          type: boolean
          description: >-
            Indicates if the user is forced to change their password at
            next login.
          example: true
        ipWhitelisted:
          type: boolean
          description: >-
            If true, the user IP address is subject to a deprecated IP
            address allowlist configuration.
          example: true
        customerId:
          type: string
          description: >-
            The customer ID to retrieve all account users. You can use the
            alias my_customer to represent the account customerId.
          readOnly: true
          example: '500123'
        orgUnitPath:
          type: string
          description: >-
            The full path of the parent organization associated with the
            user. If the parent organization is the top-level, it is
            represented as a forward slash (/).
          example: example_value
        isMailboxSetup:
          type: boolean
          description: >-
            Indicates if the user Gmail mailbox has been created.
          readOnly: true
          example: true
        includeInGlobalAddressList:
          type: boolean
          description: >-
            Indicates if the user profile is visible in the Google
            Workspace global address list.
          example: true
        thumbnailPhotoUrl:
          type: string
          format: uri
          description: >-
            Photo URL of the user. The URL might be temporary or
            private. Read-only.
          readOnly: true
          example: https://www.example.com
        thumbnailPhotoEtag:
          type: string
          description: ETag of the user photo.
          readOnly: true
          example: example_value
        archived:
          type: boolean
          description: Indicates if the user is archived.
          example: true
        recoveryEmail:
          type: string
          format: email
          description: Recovery email of the user.
          example: user@example.com
        recoveryPhone:
          type: string
          description: Recovery phone of the user in E.164 format.
          example: example_value
        isEnrolledIn2Sv:
          type: boolean
          description: >-
            Is enrolled in 2-step verification. Read-only.
          readOnly: true
          example: true
        isEnforcedIn2Sv:
          type: boolean
          description: >-
            Is 2-step verification enforced. Read-only.
          readOnly: true
          example: true
        emails:
          type: array
          description: >-
            A list of the user email addresses. The maximum allowed data
            size is 10KB.
          items:
            type: object
            properties:
              address:
                type: string
                format: email
              type:
                type: string
              customType:
                type: string
              primary:
                type: boolean
          example: user@example.com
        phones:
          type: array
          description: A list of the user phone numbers.
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
              customType:
                type: string
              primary:
                type: boolean
          example: []
        addresses:
          type: array
          description: A list of the user addresses.
          items:
            type: object
            properties:
              type:
                type: string
              customType:
                type: string
              streetAddress:
                type: string
              locality:
                type: string
              region:
                type: string
              postalCode:
                type: string
              country:
                type: string
              countryCode:
                type: string
              formatted:
                type: string
              poBox:
                type: string
              extendedAddress:
                type: string
              primary:
                type: boolean
              sourceIsStructured:
                type: boolean
          example: []
        organizations:
          type: array
          description: A list of organizations the user belongs to.
          items:
            type: object
            properties:
              name:
                type: string
              title:
                type: string
              department:
                type: string
              description:
                type: string
              costCenter:
                type: string
              location:
                type: string
              domain:
                type: string
              symbol:
                type: string
              type:
                type: string
              customType:
                type: string
              primary:
                type: boolean
              fullTimeEquivalent:
                type: integer
          example: []
        relations:
          type: array
          description: A list of the user relationships to other users.
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
              customType:
                type: string
          example: []
        externalIds:
          type: array
          description: A list of external IDs for the user.
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
              customType:
                type: string
          example: []
        websites:
          type: array
          description: A list of the user websites.
          items:
            type: object
            properties:
              value:
                type: string
                format: uri
              type:
                type: string
              customType:
                type: string
              primary:
                type: boolean
          example: []
        ims:
          type: array
          description: The user Instant Messenger (IM) accounts.
          items:
            type: object
            properties:
              im:
                type: string
              type:
                type: string
              customType:
                type: string
              protocol:
                type: string
              customProtocol:
                type: string
              primary:
                type: boolean
          example: []
        languages:
          type: array
          description: The user languages.
          items:
            type: object
            properties:
              languageCode:
                type: string
              customLanguage:
                type: string
              preference:
                type: string
          example: []
        gender:
          type: object
          description: The user gender.
          properties:
            type:
              type: string
            customGender:
              type: string
            addressMeAs:
              type: string
          example: example_value
        keywords:
          type: array
          description: The user keywords.
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
              customType:
                type: string
          example: []
        locations:
          type: array
          description: The user locations.
          items:
            type: object
            properties:
              area:
                type: string
              buildingId:
                type: string
              customType:
                type: string
              deskCode:
                type: string
              floorName:
                type: string
              floorSection:
                type: string
              type:
                type: string
          example: []
        notes:
          type: object
          description: Notes for the user.
          properties:
            value:
              type: string
            contentType:
              type: string
              enum:
              - text_plain
              - text_html
          example: example_value
        customSchemas:
          type: object
          description: >-
            Custom fields of the user. Keys are schema names and values
            are objects with field name/value pairs.
          additionalProperties:
            type: object
            additionalProperties: true
          example: example_value
      required:
      - primaryEmail
      - name

    UserName:
      type: object
      description: A user name object containing given, family, and full name.
      properties:
        givenName:
          type: string
          description: >-
            The user first name. Required when creating a user account.
          maxLength: 60
          example: example_value
        familyName:
          type: string
          description: >-
            The user last name. Required when creating a user account.
          maxLength: 60
          example: example_value
        fullName:
          type: string
          description: The user full name formed by concatenating first and last name values.
          readOnly: true
          example: example_value
        displayName:
          type: string
          description: The user display name.
          example: example_value
      required:
      - givenName
      - familyName

    Users:
      type: object
      description: A paginated list of user resources.
      properties:
        kind:
          type: string
          description: The type of the API resource.
          default: admin#directory#users
          readOnly: true
          example: example_value
        etag:
          type: string
          description: ETag of the resource.
          readOnly: true
          example: example_value
        users:
          type: array
          description: A list of user objects.
          items:
            $ref: '#/components/schemas/User'
          example: []
        nextPageToken:
          type: string
          description: Token for retrieving the next page of results.
          example: example_value
        trigger_event:
          type: string
          description: Event that triggered this response (for push notifications).
          readOnly: true

          example: example_value
    Group:
      type: object
      description: >-
        A Google Workspace group. JSON representation of a group resource
        from the Admin SDK Directory API.
      properties:
        kind:
          type: string
          description: The type of the API resource.
          default: admin#directory#group
          readOnly: true
          example: example_value
        id:
          type: string
          description: The unique ID of a group.
          readOnly: true
          example: abc123
        etag:
          type: string
          description: ETag of the resource.
          readOnly: true
          example: example_value
        email:
          type: string
          format: email
          description: >-
            The group email address. This property is required when creating
            a group. Group email addresses must be unique.
          example: user@example.com
        name:
          type: string
          description: The group display name.
          example: Example Title
        description:
          type: string
          description: >-
            An extended description to help users determine the purpose of
            a group. Maximum 4,096 characters.
          maxLength: 4096
          example: A sample description.
        adminCreated:
          type: boolean
          description: >-
            Value is true if this group was created by an administrator
            rather than a user.
          readOnly: true
          example: true
        directMembersCount:
          type: string
          description: >-
            The number of users that are direct members of the group.
            Members of child groups are not counted.
          readOnly: true
          example: example_value
        aliases:
          type: array
          description: A list of a group alias email addresses.
          readOnly: true
          items:
            type: string
            format: email
          example: []
        nonEditableAliases:
          type: array
          description: >-
            A list of the group non-editable alias email addresses that are
            outside of the account primary domain or subdomains.
          readOnly: true
          items:
            type: string
            format: email
          example: []
      required:
      - email

    Groups:
      type: object
      description: A paginated list of group resources.
      properties:
        kind:
          type: string
          description: The type of the API resource.
          default: admin#directory#groups
          readOnly: true
          example: example_value
        etag:
          type: string
          description: ETag of the resource.
          readOnly: true
          example: example_value
        groups:
          type: array
          description: A list of group objects.
          items:
            $ref: '#/components/schemas/Group'
          example: []
        nextPageToken:
          type: string
          description: Token for retrieving the next page of results.

          example: example_value
    OrgUnit:
      type: object
      description: >-
        A Google Workspace organizational unit. JSON representation of an
        org unit resource from the Admin SDK Directory API. The hierarchy
        is limited to 35 levels of depth.
      properties:
        kind:
          type: string
          description: The type of the API resource.
          default: admin#directory#orgUnit
          readOnly: true
          example: example_value
        etag:
          type: string
          description: ETag of the resource.
          readOnly: true
          example: example_value
        name:
          type: string
          description: >-
            The organizational unit path name. For example, an
            organizational unit with parent path /corp and name sales is
            derived as /corp/sales.
          example: Example Title
        description:
          type: string
          description: Description of the organizational unit.
          example: A sample description.
        orgUnitPath:
          type: string
          description: >-
            The full path to the organizational unit. The orgUnitPath is a
            derived property. When listed, it is derived from parentOrgUnitPath
            and the organizational unit name.
          readOnly: true
          example: example_value
        orgUnitId:
          type: string
          description: The unique ID of the organizational unit.
          readOnly: true
          example: '500123'
        parentOrgUnitPath:
          type: string
          description: >-
            The organizational unit path of the parent organizational unit.
            Required unless parentOrgUnitId is set.
          example: example_value
        parentOrgUnitId:
          type: string
          description: >-
            The unique ID of the parent organizational unit. Required unless
            parentOrgUnitPath is set.
          example: '500123'
        blockInheritance:
          type: boolean
          description: >-
            Deprecated. Setting this field has no effect.
          deprecated: true
          example: true
      required:
      - name

    OrgUnits:
      type: object
      description: A list of organizational unit resources.
      properties:
        kind:
          type: string
          description: The type of the API resource.
          default: admin#directory#orgUnits
          readOnly: true
          example: example_value
        etag:
          type: string
          description: ETag of the resource.
          readOnly: true
          example: example_value
        organizationUnits:
          type: array
          description: A list of organizational unit objects.
          items:
            $ref: '#/components/schemas/OrgUnit'

          example: []
    Error:
      type: object
      description: An error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: The HTTP status code.
            message:
              type: string
              description: A human-readable description of the error.
            errors:
              type: array
              description: Detailed error information.
              items:
                type: object
                properties:
                  domain:
                    type: string
                  reason:
                    type: string
                  message:
                    type: string

  # ──────────────────────────────────────────────
  # Reusable Responses
  # ──────────────────────────────────────────────

          example: example_value
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required. The request did not include valid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The authenticated user does not have permission to perform this
        operation. Ensure the correct admin scopes are authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'