Skip to main content
The Users API gives you full control over everyone in your Google workspace. Whether you need to programmatically provision new team members, update roles as responsibilities shift, or remove access for departed colleagues, every user lifecycle operation is available through a consistent REST interface. All requests require a valid Bearer token in the Authorization header.

​
List Users

Retrieve a paginated list of all users in your workspace. Use the query parameters below to filter results by role or account status. GET https://api.google.com/v1/users

​
Query Parameters

​
page
integer
The page number to retrieve. Defaults to 1.
​
per_page
integer
default:20
Number of users to return per page. Defaults to 20. Maximum is 100.
​
role
string
Filter by user role. Accepted values: admin, editor, viewer.
​
status
string
Filter by account status. Accepted values: active, inactive.

​
Example Request

curl -X GET "https://api.google.com/v1/users?page=1&per_page=20&role=editor&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

{
  "success": true,
  "data": [
    {
      "id": "usr_abc123",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "editor",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 42 }
}

​
Response Fields

​
success
boolean
Indicates whether the request completed successfully.
​
data
array
Array of user objects matching the query.
​
meta
object
Pagination metadata including page, per_page, and total record count.

​
Get User

Fetch the full profile for a single user by their unique ID. GET https://api.google.com/v1/users/:id

​
Path Parameters

​
id
string
required
The unique identifier of the user (e.g., usr_abc123).

​
Example Request

curl -X GET "https://api.google.com/v1/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "role": "editor",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
Create User

Invite a new user to your workspace by providing their email address, display name, and assigned role. POST https://api.google.com/v1/users

​
Body Parameters

​
email
string
required
The email address of the new user. Must be unique within the workspace.
​
name
string
required
The display name for the user.
​
role
string
required
The role to assign to the user. Accepted values: admin, editor, viewer.

​
Example Request

curl -X POST "https://api.google.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@example.com",
    "name": "Alex Johnson",
    "role": "editor"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "usr_def456",
    "email": "alex@example.com",
    "name": "Alex Johnson",
    "role": "editor",
    "status": "active",
    "created_at": "2024-06-01T08:00:00Z"
  }
}
A welcome email is automatically sent to the new user upon successful creation. The user’s account is immediately active.

​
Update User

Modify one or more fields on an existing user. Only include the fields you want to change — all other fields remain unchanged. PATCH https://api.google.com/v1/users/:id

​
Path Parameters

​
id
string
required
The unique identifier of the user to update.

​
Body Parameters

​
name
string
Updated display name for the user.
​
role
string
Updated role. Accepted values: admin, editor, viewer.
​
status
string
Updated account status. Accepted values: active, inactive.

​
Example Request

curl -X PATCH "https://api.google.com/v1/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "status": "active"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "role": "admin",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
Remove User

Permanently remove a user from your workspace. DELETE https://api.google.com/v1/users/:id
Removing a user is a permanent action. The user will immediately lose access to your workspace and all associated resources. This cannot be undone. If you need to temporarily suspend access, consider setting the user’s status to inactive via the Update User endpoint instead.

​
Path Parameters

​
id
string
required
The unique identifier of the user to remove.

​
Example Request

curl -X DELETE "https://api.google.com/v1/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

A successful deletion returns an HTTP 204 No Content response with an empty body, confirming the user has been removed.

​
Error Reference

The request body is missing required fields or contains invalid values. Check that email, name, and role are all provided when creating a user.
Your API key is missing or invalid. Ensure you are passing a valid Bearer token in the Authorization header.
No user exists with the specified id. Verify the ID and try again.
A user with the given email address already exists in the workspace.
The request was well-formed but contains semantic errors, such as an unrecognized role or status value.