Users and Groups API Docs

Introduction to the Team API 

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can begin making requests to the Team API endpoints listed below.

Team 

The Team API endpoints are intended for use with admin accounts connected to your Kloudless application.

Admins can grant access to their entire organization’s data. Requests can then be performed on behalf of each user in the organization by setting the header X-Kloudless-As-User to the appropriate user’s ID. These user IDs can be retrieved by listing all of the team’s users.

The following services require user impersonation via X-Kloudless-As-User to access that user’s data via an admin account:

  • box

  • dropbox

  • gdrive

  • google_calendar

  • gmail

  • outlook_calendar

  • outlook_email

  • exchange

  • exchange_email

  • onedrivebiz

Other services such as s3, sharepoint and egnyte do not require, nor allow, users to be impersonated as all data is already available to admin users.

The Team API has the following available object types:

  • user

  • group

For all requests in this section, the account_id in the URL must correspond to an admin account that has authorized access to team data.

v2 Team API

Check out our v2 Team API for more detailed User, Group, and Membership information.

The v2 API also supports creating, updating, and deleting users and groups, as well as modifying group membership.

A subset of services are supported, with more on the roadmap.

List Users 

List usersGET /accounts/{account_id}/team/users{?page_size,page}

Supported services:

  • box

  • dropbox

  • egnyte

  • exchange

  • exchange_email

  • gdrive

  • google_calendar

  • gmail

  • onedrivebiz

  • outlook_calendar

  • outlook_email

  • s3

  • salesforce

  • sharepoint

  • slack

  • ms_teams

The response contains the following information:

  • count Number of users on this page.

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of users. Each user object has:

    • id The ID of the user. Use this as the value of the X-Kloudless-As-User header to perform API requests as this user.

    • name The name of the user.

    • email An email associated with the user.

    • calendar_id The ID of the user’s calendar, for use with the Kloudless Calendar API. This is currently supported for Google and Microsoft accounts, and Exchange Calendar.

    • type Always user.

    • api Always team.

    • href The absolute URL to get the object’s metadata.

  • type Always object_list.

  • api Always team.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/team/users'
  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000. Page sizes are treated as advisory. If a page_size is outside the range supported by a service, the closest supported value will be used.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

    raw
    string (optional) 

    Raw query parameters can be passed-through to upstream services by setting raw[query_name]=query_value in the query string. Note that the query_name and query_value must be supported in the upstream services. Supported by:

    • sharepoint

    • onedrivebiz

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "count": 1,
  "next_page": null,
  "page": "1",
  "objects": [
    {
      "id": "u4806226",
      "id_type": "default",
      "name": "Test User",
      "email": "user@test.com",
      "calendar_id": "fdXNlckB0ZXN0LmNvbQ==",
      "type": "user",
      "api": "team",
      "ids": {
        "default": "u4806226",
        "team": "t3141592"
      },
      "href": "https://api.kloudless.com/v1/accounts/123/team/users/u4806226"
    }
  ],
  "type": "object_list",
  "api": "team"
}

Retrieve a User 

Retrieve a userGET /accounts/{account_id}/team/users/{user_id}

Supported services:

  • box

  • dropbox

  • egnyte

  • exchange

  • exchange_email

  • gdrive

  • google_calendar

  • onedrivebiz

  • s3

  • salesforce

  • sharepoint

  • slack

The response contains the following information:

  • id The ID of the user. Use this as the value of the X-Kloudless-As-User header to perform API requests as this user.

  • name The name of the user.

  • email An email associated with the user.

  • calendar_id The ID of the user’s calendar, for use with the Kloudless Calendar API. This is currently supported for Google and Microsoft accounts, and Exchange Calendar.

  • type Always user.

  • api Always team.

  • ids Optional. If there are multiple IDs returned by Kloudless to refer to this object in API responses, this attribute will be an object that maps all types of IDs that could be returned to their current values. Here are the possible types of IDs:

    • default: An ID that refers to this user account. Unique within the upstream service.
    • team: An ID that refers to this user within an admin account. Unique within the admin account.
    • login: Similar to default, but based on a property chosen by or assigned to the user instead, such as the user’s email address or username. This ID could change if the underlying value is updated. Usually based on the user’s email address. Unique within the upstream service.
    • username: The username of this user as specified in the upstream service. This ID could change if the underlying value is updated.
    • impersonation: (Dropbox specific) An ID that refers to a non-admin user’s team member ID, accessible by a Dropbox admin.
    • admin-impersonation: (Dropbox specific) An ID that refers to an admin user’s team member ID, accessible by a Dropbox admin.

  • id_type Optional. Refers to the type of id value, for objects with multiple IDs. This value is only present if retrieving the object’s metadata would return an ids attribute with multiple values.

  • href The absolute URL to get the object’s metadata.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/team/users/u4806226'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "u4806226",
  "id_type": "default",
  "name": "Test User",
  "email": "user@test.com",
  "calendar_id": "fdXNlckB0ZXN0LmNvbQ==",
  "type": "user",
  "api": "team",
  "ids": {
    "default": "u4806226",
    "team": "t3141592"
  },
  "href": "https://api.kloudless.com/v1/accounts/123/team/users/u4806226"
}

List a User's Group Memberships 

List a user's group membershipsGET /accounts/{account_id}/team/users/{user_id}/memberships{?page_size,page}

Supported services:

  • box

  • dropbox

  • gdrive

  • google_calendar

  • onedrivebiz

  • s3

  • salesforce

  • sharepoint

  • slack

The response contains the following information:

  • count Number of objects on this page.

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of groups the user is in. Each group object has:

    • id The ID of the group.

    • name The name of the group.

    • role The role of the user in the group. May be one of the following:

      • member: The user is a member of the group.
      • admin: The user is an admin of the group.

    • type Always group.

    • api Always team.

    • email An email associated with the group, if any. Not present if unavailable.

  • type Always object_list.

  • api Always team.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/team/users/u4806226/memberships'
  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
    "count": 1,
    "next_page": null,
    "page": "1",
    "objects": [
        {
            "id": "g982734",
            "name": "Test Group",
            "role": "admin",
            "type": "group",
            "api": "team"
        },
    ],
    "type": "object_list",
    "api": "team",
}

List Groups 

List groupsGET /accounts/{account_id}/team/groups{?page_size,page}

Supported services:

  • box

  • dropbox

  • egnyte

  • gdrive

  • google_calendar

  • onedrivebiz

  • s3

  • salesforce

  • sharepoint

  • slack

  • ms_teams

The response contains the following information:

  • count Number of objects on this page.

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of groups. Each group has:

    • id The ID of the group.

    • name The name of the group.

    • type Always group.

    • email An email associated with the group, if any. Not present if unavailable.

    • api Always team.

    • href The absolute URL to get the object’s metadata.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/team/groups'
  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000. Page sizes are treated as advisory. If a page_size is outside the range supported by a service, the closest supported value will be used.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

    raw
    string (optional) 

    Raw query parameters can be passed-through to upstream services by setting raw[query_name]=query_value in the query string. Note that the query_name and query_value must be supported in the upstream services. Supported by:

    • sharepoint

    • onedrivebiz

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "count": 1,
  "next_page": null,
  "page": "1",
  "objects": [
    {
      "id": "g982734",
      "name": "Test Group",
      "type": "group",
      "api": "team",
      "href": "https://api.kloudless.com/v1/accounts/123/team/groups/g982734"
    }
  ],
  "type": "object_list",
  "api": "team"
}

Retrieve a Group 

Retrieve a groupGET /accounts/{account_id}/team/groups/{group_id}

Supported services:

  • box

  • dropbox

  • egnyte

  • gdrive

  • google_calendar

  • onedrivebiz

  • s3

  • salesforce

  • sharepoint

  • slack

The response contains the following information:

  • id The ID of the group.

  • name The name of the group.

  • type Always group.

  • email An email associated with the group, if any. Not present if unavailable.

  • api Always team.

  • ids Optional. If there are multiple IDs returned by Kloudless to refer to this object in API responses, this attribute will be an object that maps all types of IDs that could be returned to their current values. Here are the possible types of IDs:

    • default: An ID that refers to this group. Unique within the upstream service.
    • name: The name of the group as defined in the upstream service. This ID may change if the underlying value changes.
    • login: Similar to default, but based on a property chosen by or assigned to the group, such as the group’s email address. This ID could change if the underlying value is updated. Unique within the upstream service.

  • id_type Optional. Refers to the type of id value, for objects with multiple IDs. Only present if retrieving the object’s metadata would return an id attribute with multiple values.

  • href The absolute URL to get the object’s metadata.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/team/groups/g982734'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "g982734",
  "name": "Test Group",
  "type": "group",
  "api": "team",
  "href": "https://api.kloudless.com/v1/accounts/123/team/groups/g982734"
}

List a Group's Members 

List a group's membersGET /accounts/{account_id}/team/groups/{group_id}/members{?page_size,page}

Supported services:

  • box

  • dropbox

  • egnyte

  • gdrive

  • google_calendar

  • onedrivebiz

  • s3

  • salesforce

  • sharepoint

  • slack

The response contains the following information:

  • count Number of objects on this page.

  • next_page The value to provide in the request’s page query parameter to retrieve the next page. This will be null if there are no more pages.

  • objects List of the group’s members, which include users and sub-groups. Each object will have the following attributes as well as any additional valid object attributes that are available:

    • id The ID of the member.

    • name The name of the member.

    • role The role of the member in the group. See role in group memberships.

    • type Either user or group.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/team/groups/g982734/members'
  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000. Page sizes are treated as advisory. If page_size is outside the range supported by a service, the closest supported value will be used.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
    "count": 1,
    "next_page": null,
    "page": "1",
    "objects": [
        {
            "id": "u4806226",
            "name": "Test User",
            "email": "user@test.com",
            "calendar_id": "fdXNlckB0ZXN0LmNvbQ==",
            "role": "admin",
            "type": "user",
            "api": "team"
        },
    ],
    "type": "object_list",
    "api": "team",
}

Full CRUD endpoints 

v2 Team API

Check out our v2 Team API for more detailed User, Group, and Membership information.

The v2 API also supports creating, updating, and deleting users and groups, as well as modifying group membership.

A subset of services are supported, with more on the roadmap.