> ## Documentation Index
> Fetch the complete documentation index at: https://the-early-spring18.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Users API: List, Invite, and Manage Account Members

> Use GET, POST, and PATCH on /v1/users to list current members, invite new users by email, and update roles. Admin scope required for write operations.

The Users API lets you programmatically manage every member of your Google account — from listing current users and their roles, to inviting new collaborators, to updating permissions as your team evolves. All user management operations are scoped to your account, meaning you only ever read or modify members who belong to the account associated with your API key. Role-based access control ensures that sensitive operations like inviting and updating users require the appropriate admin scope, protecting your team from unintended changes.

## GET /v1/users

Retrieve a paginated list of all users currently associated with your account. This endpoint requires **read** scope and returns each user's ID, email address, assigned role, and the timestamp at which they joined.

### Query Parameters

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

<ParamField query="limit" type="integer" default="20">
  The number of users to return per page. Maximum is `100`.
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.google.com/v1/users \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "data": {
    "users": [
      {
        "id": "usr_abc123",
        "email": "alice@example.com",
        "role": "admin",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}
```

### Response Fields

<ResponseField name="users" type="array">
  An array of user objects belonging to your account.

  <Expandable title="users[]">
    <ResponseField name="id" type="string">
      The unique identifier for the user, prefixed with `usr_`.
    </ResponseField>

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

    <ResponseField name="role" type="string">
      The user's assigned role. Either `member` or `admin`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The ISO 8601 timestamp at which the user joined the account, in UTC.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  The total number of users in the account across all pages.
</ResponseField>

***

## POST /v1/users

Invite a new user to your account by email address. The invited user will receive an email with instructions to accept the invitation and set up their credentials. This endpoint requires **admin** scope and returns a `201 Created` response on success.

### Request Body

<ParamField body="email" type="string" required>
  The email address of the person you want to invite. An invitation email will be sent to this address. The address must not already belong to an existing member of your account.
</ParamField>

<ParamField body="role" type="string" required>
  The role to assign to the new user. Accepted values:

  * `member` — standard access; can read and create data objects
  * `admin` — full access; can manage users, billing, and all account settings
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.google.com/v1/users \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"email": "bob@example.com", "role": "member"}'
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "data": {
    "id": "usr_def456",
    "email": "bob@example.com",
    "role": "member",
    "status": "invited",
    "created_at": "2024-06-01T12:00:00Z"
  }
}
```

### Response Fields

<ResponseField name="id" type="string">
  The unique identifier for the newly invited user, prefixed with `usr_`.
</ResponseField>

<ResponseField name="email" type="string">
  The email address to which the invitation was sent.
</ResponseField>

<ResponseField name="role" type="string">
  The role assigned to the user at the time of invitation. Either `member` or `admin`.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the user. Set to `invited` immediately after creation; transitions to `active` once the user accepts the invitation and completes account setup.
</ResponseField>

<ResponseField name="created_at" type="string">
  The ISO 8601 timestamp at which the invitation was created, in UTC.
</ResponseField>

<Info>
  The returned user object includes a `status` field set to `invited` until the user accepts the invitation and completes account setup, at which point it transitions to `active`.
</Info>

***

## PATCH /v1/users/{id}

Update the role of an existing account member. You can use this endpoint to promote a member to admin or downgrade an admin to a standard member. This endpoint requires **admin** scope and returns the updated user object on success.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the user you want to update, for example `usr_abc123`.
</ParamField>

### Request Body

<ParamField body="role" type="string" required>
  The new role to assign to the user. Accepted values are `member` and `admin`.
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL 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"}'
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "data": {
    "id": "usr_abc123",
    "email": "alice@example.com",
    "role": "admin",
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

### Response Fields

<ResponseField name="id" type="string">
  The unique identifier of the updated user, prefixed with `usr_`.
</ResponseField>

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

<ResponseField name="role" type="string">
  The user's newly assigned role. Either `member` or `admin`.
</ResponseField>

<ResponseField name="created_at" type="string">
  The ISO 8601 timestamp at which the user originally joined the account, in UTC.
</ResponseField>

<Tip>
  If you need to change multiple users' roles at once, send each `PATCH` request independently. Batch role updates are not supported in a single API call.
</Tip>

<Warning>
  Removing or downgrading a user **immediately revokes their access** to all account resources. If the user is currently working in a session, their next API call or page load will return a `403 Forbidden` response. Make sure you have communicated the change before modifying critical admin accounts.
</Warning>