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

page · integer · default: "1"

The page number to retrieve. Starts at 1.

limit · integer · default: "20"

The number of users to return per page. Maximum is 100.

Example Request

cURL

curl https://api.google.com/v1/users \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "data": {
    "users": [
      {
        "id": "usr_abc123",
        "email": "[e-mail]",
        "role": "admin",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}

Response Fields

users · array

An array of user objects belonging to your account.

Show users[]

id · string

The unique identifier for the user, prefixed with usr_.

email · string

The email address associated with the user’s account.

role · string

The user’s assigned role. Either member or admin.

created_at · string

The ISO 8601 timestamp at which the user joined the account, in UTC.

total · integer

The total number of users in the account across all pages.

---

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

email · 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.

role · 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

Example Request

cURL

curl -X POST https://api.google.com/v1/users \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email": "[e-mail]", "role": "member"}'

Example Response

{
  "data": {
    "id": "usr_def456",
    "email": "[e-mail]",
    "role": "member",
    "status": "invited",
    "created_at": "2024-06-01T12:00:00Z"
  }
}

Response Fields

id · string

The unique identifier for the newly invited user, prefixed with usr_.

email · string

The email address to which the invitation was sent.

role · string

The role assigned to the user at the time of invitation. Either member or admin.

status · 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.

created_at · string

The ISO 8601 timestamp at which the invitation was created, in UTC.

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.

---

PATCH /v1/users/

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

id · string · required

The unique identifier of the user you want to update, for example usr_abc123.

Request Body

role · string · required

The new role to assign to the user. Accepted values are member and admin.

Example Request

cURL

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"}'

Example Response

{
  "data": {
    "id": "usr_abc123",
    "email": "[e-mail]",
    "role": "admin",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Response Fields

id · string

The unique identifier of the updated user, prefixed with usr_.

email · string

The email address associated with the user’s account.

role · string

The user’s newly assigned role. Either member or admin.

created_at · string

The ISO 8601 timestamp at which the user originally joined the account, in UTC.

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.

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.