Google Workspace Admin
by @byungkyu
Google Workspace Admin SDK integration with managed OAuth. This is a write-capable administrative integration for users, groups, organizational units, roles,...
clawhub install google-workspace-adminπ About This Skill
name: google-workspace-admin description: | Google Workspace Admin SDK integration with managed OAuth. This is a write-capable administrative integration for users, groups, organizational units, roles, and domain settings. Only connect with a least-privileged Google admin account, restrict OAuth scopes to the specific resources needed, and revoke the connection after use. All write operations require explicit user approval showing the exact HTTP method, endpoint path, and target resource identifier before execution. Use this skill only when users need Google Workspace administration. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: π§ homepage: "https://maton.ai" requires: env: - MATON_API_KEY
Google Workspace Admin
Access the Google Workspace Admin SDK with managed OAuth authentication. Read and manage users, groups, organizational units, roles, and domain settings for Google Workspace. This is high-impact administrative access β connect only with least-privilege OAuth scopes and revoke the connection when administrative work is complete.
Quick Start
# List users in the domain
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer&maxResults=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Base URL
https://api.maton.ai/google-workspace-admin/{endpoint-path}
The gateway proxies requests to admin.googleapis.com and automatically injects your OAuth token. Only the endpoints documented in the API Reference section below are supported β always use specific endpoint paths from that section rather than constructing arbitrary paths. Before any write call, display the exact HTTP method, full endpoint path, and target resource identifier (user email, group address, OU path) for user review.
Authentication
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEY
Environment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"
Getting Your API Key
1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key
Connection Management
Manage your Google OAuth connections at https://api.maton.ai.
List Connections
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=google-workspace-admin&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Create Connection
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-workspace-admin'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Get Connection
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Response:
{
"connection": {
"connection_id": "{connection_id}",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "google-workspace-admin",
"metadata": {}
}
}
Open the returned url in a browser to complete OAuth authorization.
Delete Connection
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Specifying Connection
If you have multiple Google Workspace Admin connections, specify which one to use with the Maton-Connection header:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
If you have multiple connections, always include this header to ensure requests go to the intended account.
Security & Permissions
Maton-Connection header with the correct connection ID on every request to ensure it targets the intended Google Workspace account.DELETE /google-workspace-admin/admin/directory/v1/users/jane@company.com).
2. The target resource identifier (user email, group address, OU path, role name).
3. A clear description of the intended effect and consequences (e.g., "This will permanently delete user 'jane@company.com', removing their account, email, and Drive data").
4. Wait for explicit user confirmation before proceeding.
API Reference
Users
#### List Users
GET /google-workspace-admin/admin/directory/v1/users?customer=my_customer&maxResults=100
Query parameters:
customer - Customer ID or my_customer for your domain (required)domain - Filter by specific domainmaxResults - Maximum results per page (1-500, default 100)orderBy - Sort by email, familyName, or givenNamequery - Search query (e.g., email:john*, name:John*)pageToken - Token for paginationExample:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer&query=email:john*')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Response:
{
"kind": "admin#directory#users",
"users": [
{
"id": "123456789",
"primaryEmail": "john@example.com",
"name": {
"givenName": "John",
"familyName": "Doe",
"fullName": "John Doe"
},
"isAdmin": false,
"isDelegatedAdmin": false,
"suspended": false,
"creationTime": "2024-01-15T10:30:00.000Z",
"lastLoginTime": "2025-02-01T08:00:00.000Z",
"orgUnitPath": "/Sales"
}
],
"nextPageToken": "..."
}
#### Get User
GET /google-workspace-admin/admin/directory/v1/users/{userKey}
userKey can be the user's primary email or unique user ID.
#### Create User
POST /google-workspace-admin/admin/directory/v1/users
Content-Type: application/json{
"primaryEmail": "newuser@example.com",
"name": {
"givenName": "Jane",
"familyName": "Smith"
},
"password": "temporaryPassword123!",
"changePasswordAtNextLogin": true,
"orgUnitPath": "/Engineering"
}
#### Update User
PUT /google-workspace-admin/admin/directory/v1/users/{userKey}
Content-Type: application/json{
"name": {
"givenName": "Jane",
"familyName": "Smith-Johnson"
},
"suspended": false,
"orgUnitPath": "/Sales"
}
#### Patch User (partial update)
PATCH /google-workspace-admin/admin/directory/v1/users/{userKey}
Content-Type: application/json{
"suspended": true
}
#### Delete User
DELETE /google-workspace-admin/admin/directory/v1/users/{userKey}
#### Make User Admin
POST /google-workspace-admin/admin/directory/v1/users/{userKey}/makeAdmin
Content-Type: application/json{
"status": true
}
Groups
#### List Groups
GET /google-workspace-admin/admin/directory/v1/groups?customer=my_customer
Query parameters:
customer - Customer ID or my_customer (required)domain - Filter by domainmaxResults - Maximum results (1-200)userKey - List groups for a specific user#### Get Group
GET /google-workspace-admin/admin/directory/v1/groups/{groupKey}
groupKey can be the group's email or unique ID.
#### Create Group
POST /google-workspace-admin/admin/directory/v1/groups
Content-Type: application/json{
"email": "engineering@example.com",
"name": "Engineering Team",
"description": "All engineering staff"
}
#### Update Group
PUT /google-workspace-admin/admin/directory/v1/groups/{groupKey}
Content-Type: application/json{
"name": "Engineering Department",
"description": "Updated description"
}
#### Delete Group
DELETE /google-workspace-admin/admin/directory/v1/groups/{groupKey}
Group Members
#### List Members
GET /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members
#### Add Member
POST /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members
Content-Type: application/json{
"email": "user@example.com",
"role": "MEMBER"
}
Roles: OWNER, MANAGER, MEMBER
#### Update Member Role
PATCH /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members/{memberKey}
Content-Type: application/json{
"role": "MANAGER"
}
#### Remove Member
DELETE /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members/{memberKey}
Organizational Units
#### List Org Units
GET /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits
Query parameters:
type - all (default) or childrenorgUnitPath - Parent org unit path#### Get Org Unit
GET /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath}
#### Create Org Unit
POST /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits
Content-Type: application/json{
"name": "Engineering",
"parentOrgUnitPath": "/",
"description": "Engineering department"
}
#### Update Org Unit
PUT /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath}
Content-Type: application/json{
"description": "Updated description"
}
#### Delete Org Unit
DELETE /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath}
Domains
#### List Domains
GET /google-workspace-admin/admin/directory/v1/customer/my_customer/domains
#### Get Domain
GET /google-workspace-admin/admin/directory/v1/customer/my_customer/domains/{domainName}
Roles
#### List Roles
GET /google-workspace-admin/admin/directory/v1/customer/my_customer/roles
#### List Role Assignments
GET /google-workspace-admin/admin/directory/v1/customer/my_customer/roleassignments
Query parameters:
userKey - Filter by userroleId - Filter by role#### Create Role Assignment
POST /google-workspace-admin/admin/directory/v1/customer/my_customer/roleassignments
Content-Type: application/json{
"roleId": "123456789",
"assignedTo": "user_id",
"scopeType": "CUSTOMER"
}
Code Examples
JavaScript
const headers = {
'Authorization': Bearer ${process.env.MATON_API_KEY}
};// List users
const users = await fetch(
'https://api.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer',
{ headers }
).then(r => r.json());
// Create user
await fetch(
'https://api.maton.ai/google-workspace-admin/admin/directory/v1/users',
{
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({
primaryEmail: 'newuser@example.com',
name: { givenName: 'New', familyName: 'User' },
password: 'TempPass123!',
changePasswordAtNextLogin: true
})
}
);
Python
import os
import requestsheaders = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
List users
users = requests.get(
'https://api.maton.ai/google-workspace-admin/admin/directory/v1/users',
headers=headers,
params={'customer': 'my_customer'}
).json()Create user
response = requests.post(
'https://api.maton.ai/google-workspace-admin/admin/directory/v1/users',
headers=headers,
json={
'primaryEmail': 'newuser@example.com',
'name': {'givenName': 'New', 'familyName': 'User'},
'password': 'TempPass123!',
'changePasswordAtNextLogin': True
}
)
Notes
my_customer as the customer ID for your own domain/ (e.g., /Engineering/Frontend)curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.Error Handling
| Status | Meaning | |--------|---------| | 400 | Missing Google Workspace Admin connection | | 401 | Invalid or missing Maton API key | | 403 | Insufficient admin privileges | | 404 | User, group, or resource not found | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Admin SDK API |
Troubleshooting: API Key Issues
1. Check that the MATON_API_KEY environment variable is set:
echo $MATON_API_KEY
2. Verify the API key is valid by listing connections:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Troubleshooting: Invalid App Name
1. Ensure your URL path starts with google-workspace-admin. For example:
https://api.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customerhttps://api.maton.ai/admin/directory/v1/users?customer=my_customerResources
π‘ Examples
# List users in the domain
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer&maxResults=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
π Tips & Best Practices
my_customer as the customer ID for your own domain/ (e.g., /Engineering/Frontend)curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.