Introduction
# Google Workspace Admin
Access the Google Workspace Admin SDK with managed OAuth authentication. Manage users, groups, organizational units, roles, and domain settings for Google Workspace.
## Quick Start
```bash # List users in the domain python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.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://gateway.maton.ai/google-workspace-admin/{native-api-path} ```
Replace `{native-api-path}` with the actual Admin SDK API endpoint path. The gateway proxies requests to `admin.googleapis.com` and automatically injects your OAuth token.
## 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`:
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key
## Connection Management
Manage your Google OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-workspace-admin'}).encode() req = urllib.request.Request('https://ctrl.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
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "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
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.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', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
If omitted, the gateway uses the default (oldest) active connection.
## API Reference
### Users
#### List Users
```bash 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 domain - `maxResults` - Maximum results per page (1-500, default 100) - `orderBy` - Sort by `email`, `familyName`, or `givenName` - `query` - Search query (e.g., `email:john*`, `name:John*`) - `pageToken` - Token for pagination
**Example:**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.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:** ```json { "kind": "admin#directory#users", "users": [ { "id": "123456789", "primaryEmail": "[email protected]", "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
```bash GET /google-workspace-admin/admin/directory/v1/users/{userKey} ```
`userKey` can be the user's primary email or unique user ID.
#### Create User
```bash POST /google-workspace-admin/admin/directory/v1/users Content-Type: application/json
{ "primaryEmail": "[email protected]", "name": { "givenName": "Jane", "familyName": "Smith" }, "password": "temporaryPassword123!", "changePasswordAtNextLogin": true, "orgUnitPath": "/Engineering" } ```
#### Update User
```bash 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)
```bash PATCH /google-workspace-admin/admin/directory/v1/users/{userKey} Content-Type: application/json
{ "suspended": true } ```
#### Delete User
```bash DELETE /google-workspace-admin/admin/directory/v1/users/{userKey} ```
#### Make User Admin
```bash POST /google-workspace-admin/admin/directory/v1/users/{userKey}/makeAdmin Content-Type: application/json
{ "status": true } ```
### Groups
#### List Groups
```bash GET /google-workspace-admin/admin/directory/v1/groups?customer=my_customer ```
Query parameters: - `customer` - Customer ID or `my_customer` (required) - `domain` - Filter by domain - `maxResults` - Maximum results (1-200) - `userKey` - List groups for a specific user
#### Get Group
```bash GET /google-workspace-admin/admin/directory/v1/groups/{groupKey} ```
`groupKey` can be the group's email or unique ID.
#### Create Group
```bash POST /google-workspace-admin/admin/directory/v1/groups Content-Type: application/json
{ "email": "[email protected]", "name": "Engineering Team", "description": "All engineering staff" } ```
#### Update Group
```bash PUT /google-workspace-admin/admin/directory/v1/groups/{groupKey} Content-Type: application/json
{ "name": "Engineering Department", "description": "Updated description" } ```
#### Delete Group
```bash DELETE /google-workspace-admin/admin/directory/v1/groups/{groupKey} ```
### Group Members
#### List Members
```bash GET /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members ```
#### Add Member
```bash POST /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members Content-Type: application/json
{ "email": "[email protected]", "role": "MEMBER" } ```
Roles: `OWNER`, `MANAGER`, `MEMBER`
#### Update Member Role
```bash PATCH /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members/{memberKey} Content-Type: application/json
{ "role": "MANAGER" } ```
#### Remove Member
```bash DELETE /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members/{memberKey} ```
### Organizational Units
#### List Org Units
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits ```
Query parameters: - `type` - `all` (default) or `children` - `orgUnitPath` - Parent org unit path
#### Get Org Unit
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath} ```
#### Create Org Unit
```bash POST /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits Content-Type: application/json
{ "name": "Engineering", "parentOrgUnitPath": "/", "description": "Engineering department" } ```
#### Update Org Unit
```bash PUT /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath} Content-Type: application/json
{ "description": "Updated description" } ```
#### Delete Org Unit
```bash DELETE /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath} ```
### Domains
#### List Domains
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/domains ```
#### Get Domain
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/domains/{domainName} ```
### Roles
#### List Roles
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/roles ```
#### List Role Assignments
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/roleassignments ```
Query parameters: - `userKey` - Filter by user - `roleId` - Filter by role
#### Create Role Assignment
```bash 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
```javascript const headers = { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` };
// List users const users = await fetch( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer', { headers } ).then(r => r.json());
// Create user await fetch( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users', { method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ primaryEmail: '[email protected]', name: { givenName: 'New', familyName: 'User' }, password: 'TempPass123!', changePasswordAtNextLogin: true }) } ); ```
### Python
```python import os import requests
headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
# List users users = requests.get( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users', headers=headers, params={'customer': 'my_customer'} ).json()
# Create user response = requests.post( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users', headers=headers, json={ 'primaryEmail': '[email protected]', 'name': {'givenName': 'New', 'familyName': 'User'}, 'password': 'TempPass123!', 'changePasswordAtNextLogin': True } ) ```
## Notes
- Use `my_customer` as the customer ID for your own domain - User keys can be primary email or unique user ID - Group keys can be group email or unique group ID - Org unit paths start with `/` (e.g., `/Engineering/Frontend`) - Admin privileges are required for most operations - Password must meet Google's complexity requirements - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` 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:
```bash echo $MATON_API_KEY ```
2. Verify the API key is valid by listing connections:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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:
- Correct: `https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer` - Incorrect: `https://gateway.maton.ai/admin/directory/v1/users?customer=my_customer`
## Resources
- [Admin SDK Overview](https://developers.google.com/admin-sdk) - [Directory API Users](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users) - [Directory API Groups](https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups) - [Directory API Members](https://developers.google.com/admin-sdk/directory/reference/rest/v1/members) - [Directory API Org Units](https://developers.google.com/admin-sdk/directory/reference/rest/v1/orgunits) - [Directory API Domains](https://developers.google.com/admin-sdk/directory/reference/rest/v1/domains) - [Directory API Roles](https://developers.google.com/admin-sdk/directory/reference/rest/v1/roles) - [Admin SDK Guides](https://developers.google.com/admin-sdk/directory/v1/guides) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])