Worlds / Hr and identity

Google Workspace Admin API

A local Google Workspace admin console with users, organizational units, groups, Drive ownership and admin roles. Test the agent that suspends users, moves Drive files and manages group access.

Base path: /admin/directory/v1
Auth: OAuth bearer token, the world key
Endpoints: 17
Status: Active today

This reference previews the surface the Google Workspace Admin world serves in the closed beta. Paths mirror the public Google Workspace Admin API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_GOOGLE_WORKSPACE_ADMIN_URL`	This world's origin followed by `/admin/directory/v1`
`WORLDS_API_KEY`	The world key, accepted wherever Google Workspace Admin expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · googleapis

import { google } from "googleapis";

const auth = new google.auth.OAuth2();
auth.setCredentials({ access_token: process.env.WORLDS_API_KEY });

const admin = google.admin({
  version: "directory_v1",
  auth,
  rootUrl: process.env.WORLDS_GOOGLE_WORKSPACE_ADMIN_URL,
});

const { data } = await admin.users.list({ customer: "my_customer", maxResults: 20 });

API reference

17 of 17

Users

Workspace accounts with org unit and status.

GET/admin/directory/v1/usersList users
POST/admin/directory/v1/usersCreate a user
GET/admin/directory/v1/users/{userKey}Get a user
PUT/admin/directory/v1/users/{userKey}Update a user
DELETE/admin/directory/v1/users/{userKey}Delete a user
POST/admin/directory/v1/users/{userKey}/undeleteRestore a deleted user

Fields · 6

`id`	string	Unique user id
`primaryEmail`	string	Primary email address
`name`	object	givenName, familyName, fullName
`suspended`	boolean	Whether the account is suspended
`orgUnitPath`	string	Org unit the user sits in
`lastLoginTime`	datetime	Last sign in

Groups

Email groups and mailing lists.

GET/admin/directory/v1/groupsList groups
POST/admin/directory/v1/groupsCreate a group
GET/admin/directory/v1/groups/{groupKey}Get a group
DELETE/admin/directory/v1/groups/{groupKey}Delete a group

Fields · 5

`id`	string	Group id
`email`	string	Group email address
`name`	string	Group name
`description`	string	Description
`directMembersCount`	string	Number of direct members

Group members

Who belongs to each group and in what role.

GET/admin/directory/v1/groups/{groupKey}/membersList members
POST/admin/directory/v1/groups/{groupKey}/membersAdd a member
PATCH/admin/directory/v1/groups/{groupKey}/members/{memberKey}Change a member's role
DELETE/admin/directory/v1/groups/{groupKey}/members/{memberKey}Remove a member

Fields · 5

`id`	string	Member id
`email`	string	Member email
`role`	string	OWNER, MANAGER or MEMBER
`type`	string	USER, GROUP or CUSTOMER
`status`	string	ACTIVE or SUSPENDED

Org units

The org tree that settings and policies attach to.

GET/admin/directory/v1/customer/{customerId}/orgunitsList org units
POST/admin/directory/v1/customer/{customerId}/orgunitsCreate an org unit
PUT/admin/directory/v1/customer/{customerId}/orgunits/{orgUnitPath}Update an org unit

Fields · 4

`orgUnitId`	string	Org unit id
`name`	string	Org unit name
`orgUnitPath`	string	Full path
`parentOrgUnitPath`	string	Parent path

Test workflow

Prepare. Select the Google Workspace Admin setup for your workflow and review its starting records, including users, groups, group members.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Drive transfer to tom.b completed before suspension
nina.v suspended
nina.v removed from sales@ and emea@
board-materials@ posting settings unchanged
No admin role assignments changed

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Google Workspace Admin
version: 2
connector: google-workspace-admin
seed: google-workspace-admin-starter
mode: isolated
policy: >
  Offboard nina.v. Transfer her Drive files to her manager tom.b first, then
  suspend the account and remove her from all groups. Leave group settings as
  they are.
tasks:
  - id: suspend-a-leaver-and-transfer-their-drive-files-to-the-manager
    prompt: Suspend a leaver and transfer their Drive files to the manager
  - id: add-or-remove-members-from-google-groups
    prompt: Add or remove members from Google Groups
  - id: move-a-user-to-a-new-organizational-unit
    prompt: Move a user to a new organizational unit
expected:
  - Drive transfer to tom.b completed before suspension
  - nina.v suspended
  - "nina.v removed from sales@ and emea@"
  - "board-materials@ posting settings unchanged"
  - No admin role assignments changed
scenarios:
  - rate-limited
  - member-exists
  - missing-scope

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	Admin SDK returns 403 userRateLimitExceeded
`member-exists`	Adding an existing member returns 409
`missing-scope`	Domain-wide delegation lacks a scope and returns 403
`token-expired`	The service account token expires mid transfer
`transfer-in-progress`	The Drive data transfer stays in progress for minutes

Starting data

Start each run from the same records and relationships. The overview below describes the Google Workspace Admin starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
users	200 across 6 organizational units, some suspended
groups	35 groups, including all@ and external-facing lists
drive	Files owned by each user, some shared outside the domain
admin roles	Super Admin, Groups Admin and User Management Admin
aliases	Email aliases and secondary domains

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Users records

Users

Workspace accounts with org unit and status.

Field	Type	Meaning / relationship
`id`	string	Unique user id
`primaryEmail`	string	Primary email address
`name`	object	givenName, familyName, fullName
`suspended`	boolean	Whether the account is suspended
`orgUnitPath`	string	Org unit the user sits in
`lastLoginTime`	datetime	Last sign in

json · illustrative record shape

{
  "id": "<Unique user id>",
  "primaryEmail": "person@example.test",
  "name": {},
  "suspended": false,
  "orgUnitPath": "<Org unit the user sits in>",
  "lastLoginTime": "<Last sign in>"
}

See users operations

Groups records

Groups

Email groups and mailing lists.

Field	Type	Meaning / relationship
`id`	string	Group id
`email`	string	Group email address
`name`	string	Group name
`description`	string	Description
`directMembersCount`	string	Number of direct members

json · illustrative record shape

{
  "id": "<Group id>",
  "email": "person@example.test",
  "name": "<Group name>",
  "description": "<Description>",
  "directMembersCount": "<Number of direct members>"
}

See groups operations

Group members records

Group members

Who belongs to each group and in what role.

Field	Type	Meaning / relationship
`id`	string	Member id
`email`	string	Member email
`role`	string	OWNER, MANAGER or MEMBER
`type`	string	USER, GROUP or CUSTOMER
`status`	string	ACTIVE or SUSPENDED

json · illustrative record shape

{
  "id": "<Member id>",
  "email": "person@example.test",
  "role": "<OWNER, MANAGER or MEMBER>",
  "type": "<USER, GROUP or CUSTOMER>",
  "status": "<ACTIVE or SUSPENDED>"
}

See group members operations

Org units records

Org units

The org tree that settings and policies attach to.

Field	Type	Meaning / relationship
`orgUnitId`	string	Org unit id
`name`	string	Org unit name
`orgUnitPath`	string	Full path
`parentOrgUnitPath`	string	Parent path

json · illustrative record shape

{
  "orgUnitId": "<Org unit id>",
  "name": "<Org unit name>",
  "orgUnitPath": "<Full path>",
  "parentOrgUnitPath": "<Parent path>"
}

See org units operations

See the Google Workspace Admin world in the catalog