> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newport.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> The Users API lets you list, create, update, and remove users in your workspace. Supports filtering by role, status, and pagination.

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

<ParamField query="page" type="integer">
  The page number to retrieve. Defaults to `1`.
</ParamField>

<ParamField query="per_page" type="integer" default={20}>
  Number of users to return per page. Defaults to `20`. Maximum is `100`.
</ParamField>

<ParamField query="role" type="string">
  Filter by user role. Accepted values: `admin`, `editor`, `viewer`.
</ParamField>

<ParamField query="status" type="string">
  Filter by account status. Accepted values: `active`, `inactive`.
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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

<ResponseField name="success" type="boolean">
  Indicates whether the request completed successfully.
</ResponseField>

<ResponseField name="data" type="array">
  Array of user objects matching the query.

  <Expandable title="User object">
    <ResponseField name="id" type="string">
      Unique identifier for the user, prefixed with `usr_`.
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email address.
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's display name.
    </ResponseField>

    <ResponseField name="role" type="string">
      The user's role in the workspace: `admin`, `editor`, or `viewer`.
    </ResponseField>

    <ResponseField name="status" type="string">
      The user's account status: `active` or `inactive`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp for when the user was added to the workspace.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata including `page`, `per_page`, and `total` record count.
</ResponseField>

***

## Get User

Fetch the full profile for a single user by their unique ID.

**`GET https://api.google.com/v1/users/:id`**

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the user (e.g., `usr_abc123`).
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://api.google.com/v1/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "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

<ParamField body="email" type="string" required>
  The email address of the new user. Must be unique within the workspace.
</ParamField>

<ParamField body="name" type="string" required>
  The display name for the user.
</ParamField>

<ParamField body="role" type="string" required>
  The role to assign to the user. Accepted values: `admin`, `editor`, `viewer`.
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "success": true,
  "data": {
    "id": "usr_def456",
    "email": "alex@example.com",
    "name": "Alex Johnson",
    "role": "editor",
    "status": "active",
    "created_at": "2024-06-01T08:00:00Z"
  }
}
```

<Note>
  A welcome email is automatically sent to the new user upon successful creation. The user's account is immediately active.
</Note>

***

## 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

<ParamField path="id" type="string" required>
  The unique identifier of the user to update.
</ParamField>

### Body Parameters

<ParamField body="name" type="string">
  Updated display name for the user.
</ParamField>

<ParamField body="role" type="string">
  Updated role. Accepted values: `admin`, `editor`, `viewer`.
</ParamField>

<ParamField body="status" type="string">
  Updated account status. Accepted values: `active`, `inactive`.
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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`**

<Warning>
  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.
</Warning>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the user to remove.
</ParamField>

### Example Request

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="401 Unauthorized">
    Your API key is missing or invalid. Ensure you are passing a valid Bearer token in the `Authorization` header.
  </Accordion>

  <Accordion title="404 Not Found">
    No user exists with the specified `id`. Verify the ID and try again.
  </Accordion>

  <Accordion title="409 Conflict">
    A user with the given email address already exists in the workspace.
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    The request was well-formed but contains semantic errors, such as an unrecognized role or status value.
  </Accordion>
</AccordionGroup>