Users API: List, Create, Update, and Remove Workspace Users

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

integer

The page number to retrieve. Defaults to 1.

integer

default:20

Number of users to return per page. Defaults to 20. Maximum is 100.

string

Filter by user role. Accepted values: admin, editor, viewer.

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

boolean

Indicates whether the request completed successfully.

array

Array of user objects matching the query.

Show User object

string

Unique identifier for the user, prefixed with usr_.

string

The user’s email address.

string

The user’s display name.

string

The user’s role in the workspace: admin, editor, or viewer.

string

The user’s account status: active or inactive.

string

ISO 8601 timestamp for when the user was added to the workspace.

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

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

string

required

The email address of the new user. Must be unique within the workspace.

string

required

The display name for the user.

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

string

required

The unique identifier of the user to update.

Body Parameters

string

Updated display name for the user.

string

Updated role. Accepted values: admin, editor, viewer.

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

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

400 Bad Request

The request body is missing required fields or contains invalid values. Check that email, name, and role are all provided when creating a user.

401 Unauthorized

Your API key is missing or invalid. Ensure you are passing a valid Bearer token in the Authorization header.

404 Not Found

No user exists with the specified id. Verify the ID and try again.

409 Conflict

A user with the given email address already exists in the workspace.

422 Unprocessable Entity

The request was well-formed but contains semantic errors, such as an unrecognized role or status value.

Overview

Endpoints

Users API: List, Create, Update, and Remove Workspace Users

List Users

Query Parameters

Example Request

Example Response

Response Fields

Get User

Path Parameters

Example Request

Example Response

Create User

Body Parameters

Example Request

Example Response

Update User

Path Parameters

Body Parameters

Example Request

Example Response

Remove User

Path Parameters

Example Request

Example Response

Error Reference

​List Users

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Get User

​Path Parameters

​Example Request

​Example Response

​Create User

​Body Parameters

​Example Request

​Example Response

​Update User

​Path Parameters

​Body Parameters

​Example Request

​Example Response

​Remove User

​Path Parameters

​Example Request

​Example Response

​Error Reference

List Users

Query Parameters

Example Request

Example Response

Response Fields

Get User

Path Parameters

Example Request

Example Response

Create User

Body Parameters

Example Request

Example Response

Update User

Path Parameters

Body Parameters

Example Request

Example Response

Remove User

Path Parameters

Example Request

Example Response

Error Reference