Users and Groups API Docs


Introduction to the Team API v2 

Start with our v1 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 perform API requests to the Team API endpoints listed below.

Overview

The Team endpoints are intended for use with Admin accounts connected to your Kloudless application. Admins can authenticate access to their entire organization’s data.

Requests can then be performed on behalf of each user of the organization by setting the header X-Kloudless-As-User to the appropriate user’s ID. These 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

  • 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

  • membership

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.


Users 

User objects contain the following attributes:

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

  • updated (read-only) When the user was last updated.

  • created (read-only) When the user was created.

  • name The name of the user.

  • name_details (optional) A mapping of specific parts of the user’s name.

  • email User’s primary email address.

  • emails (optional) Alternate email addresses for the user.

  • password (write-only) The user’s password.

  • type Always user.

  • api Always team.

  • ids (read-only, 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.
  • id_type (read-only, optional) Refers to the type of id value, for objects with multiple IDs. Only present if retrieving the object’s metadata would return an ids attribute with multiple values.

  • external_id (optional) A custom ID that can be set to identify the corresponding object in an external system, such as Active Directory. e.g. An Office 365 user’s onPremisesImmutableId.

  • role The role of the user within the organization. It can be one of the following values:

    • admin
    • member (default)
    • external
  • role_name The name of the role of the user within the organization.

  • status Current state of the user, one of:

    • active (default)
    • suspended
    • inactive
  • username The unique username.

  • address (optional) Combined address string.

  • address_details (optional) Mapping of address parts.

  • addresses (optional) Alternate addresses for the user.

  • phone (optional) User’s phone number.

  • phones (optional) Alternate phone numbers.

  • organization (optional) Name of the user’s organization.

  • description (optional) A description of the user.

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

List Users 

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

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

  • egnyte

  • sharefile

Additional services supported in v1 are:

  • box

  • dropbox

  • google_calendar

  • s3

  • salesforce

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 User objects.

  • type Always object_list.

  • api Always team.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/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. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

    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",
          "type": "user",
          "api": "team",
          "ids": {
            "default": "u4806226",
            "team": "t3141592"
          },
          "href": "https://api.kloudless.com/v2/accounts/123/team/users/u4806226"
        }
      ],
      "type": "object_list",
      "api": "team"
    }

Create User 

Create UserPOST /accounts/{account_id}/team/users/{user_id}

Services currently supported are:

  • sharepoint

    • Requires email, name, password, and username to be set.
  • onedrivebiz

    • See sharepoint.
  • gdrive

    • Requires name, email, and password to be set

To create a new User, perform a POST request with a json object containing at least the writable, non-optional fields described above.

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v2/accounts/123/team/users' \
    --data-binary '{"name": "Test User", "email": "user@test.com"}'
  • RequestToggle
  • Headers

    Content-Type: application/json

    Body

    {
      "name": "Test User",
      "email": "user@test.com"
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

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

Retrieve a User 

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

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

  • egnyte

  • sharefile

Additional services supported in v1 are:

  • box

  • dropbox

  • google_calendar

  • s3

  • salesforce

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/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",
      "type": "user",
      "api": "team",
      "ids": {
        "default": "u4806226",
        "team": "t3141592"
      },
      "href": "https://api.kloudless.com/v2/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}

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

  • egnyte

  • sharefile

Additional services supported in v1 are:

  • box

  • dropbox

  • google_calendar

  • s3

  • salesforce

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 Membership objects for the groups that the user is a member of.

  • type Always object_list.

  • api Always team.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/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 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. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

    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": "mbWVycAo=",
                "type": "membership",
                "role": "member",
                "api": "team",
                "group": {
                    "id": "g982734",
                    "name": "Test Group",
                    "type": "group",
                    "api": "team",
                },
                "member": {
                    "id": "uZGVycEBtZXJwLmNvbQo=",
                    "id_type": "default",
                    "name": "Jane Doe",
                    "email": "user@test.com",
                    "type": "user",
                    "api": "team",
                    "ids" {
                        "default": "uZGVycEBtZXJwLmNvbQo=",
                        "team": "t3141592"
                    }
                }
            }
        ],
        "type": "object_list",
        "api": "team",
    }

Update User 

Update UserPATCH /accounts/{account_id}/team/users/{user_id}

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

  • egnyte

  • sharefile

To update a user, perform a PATCH request to the desired user_id with the attributes that you would like to update. Any of the non-read-only attributes can be specified in the object.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XPATCH \
    'https://api.kloudless.com/v2/accounts/34/team/users/uZGVycEBtZXJwLmNvbQo=' \
    -H "Content-Type: application/json"
    --data-binary '{"name": "Jane Doe"}'
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "uZGVycEBtZXJwLmNvbQo=",
      "id_type": "default",
      "name": "Jane Doe",
      "email": "user@test.com",
      "type": "user",
      "api": "team",
      "ids": {
        "default": "uZGVycEBtZXJwLmNvbQo=",
        "team": "t3141592"
      },
      "href": "https://api.kloudless.com/v2/accounts/123/team/users/uZGVycEBtZXJwLmNvbQo="
    }

Delete a User 

Delete a userDELETE /accounts/{account_id}/team/users/{user_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE \
    'https://api.kloudless.com/v2/accounts/34/team/users/uZGVycEBtZXJwLmNvbQo='
  • Response  204

Group 

Group objects represent collections of users and groups. They have the following attributes:

  • id (read-only) The ID of the group object, used to reference it in other requests.

  • type (read-only) Always group.

  • api (read-only) Always team.

  • modified (read-only) When the group was last modified.

  • created (read-only) When the group was created.

  • external_id (optional) A custom ID that can be set to identify the corresponding object in an external system, such as Active Directory.

  • name The group’s name.

  • email The group email address.

  • description (optional) A description of the group.

  • ids (read-only, 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.
  • id_type (read-only, optional) Refers to the type of id value, for objects with multiple IDs. 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.

List Groups 

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

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

  • egnyte

  • sharefile

Additional services supported in v1 are:

  • box

  • dropbox

  • google_calendar

  • s3

  • salesforce

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 [Group] objects.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/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. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

    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/v2/accounts/123/team/groups/g982734"
        }
      ],
      "type": "object_list",
      "api": "team"
    }

Create Group 

Create groupPOST /accounts/{account_id}/team/groups
  • sharepoint

    • Requires email and name to be set.
    • Creation of directory roles is not supported.
  • onedrivebiz

    • See sharepoint.

Example request:

curl -XPOST  -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v2/accounts/123/team/groups/' \
    --data-binary '{"name": "Test Group"}'
  • RequestToggle
  • Headers

    Content-Type: application/json

    Body

    {
      "name": "Test Group"
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

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

Retrieve a Group 

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

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

  • egnyte

  • sharefile

Additional services supported in v1 are:

  • box

  • dropbox

  • google_calendar

  • s3

  • salesforce

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/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/v2/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}

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

  • egnyte

  • sharefile

Additional services supported in v1 are:

  • box

  • dropbox

  • google_calendar

  • s3

  • salesforce

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 Membership objects representing the group members.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/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 a page_size is outside the range supported by a service, the closest supported value will be used.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

    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": "mbWVycAo=",
                "type": "membership",
                "role": "member",
                "api": "team",
                "group": {
                    "id": "g982734",
                    "name": "Test Group",
                    "type": "group",
                    "api": "team",
                },
                "member": {
                    "id": "uZGVycEBtZXJwLmNvbQo=",
                    "id_type": "default",
                    "name": "Jane Doe",
                    "email": "user@test.com",
                    "type": "user",
                    "api": "team",
                    "ids" {
                        "default": "uZGVycEBtZXJwLmNvbQo=",
                        "team": "t3141592"
                    }
                }
            }
        ],
        "type": "object_list",
        "api": "team",
    }

Update Group 

Update groupPATCH /accounts/{account_id}/team/groups/{group_id}

Services currently supported are:

  • sharepoint

  • onedrivebiz

  • gdrive

To update a group, perform a PATCH request to the desired group_id with the attributes you would like to update. Any of the non-read-only attributes can be specified in the object.

Example request:

curl -XPATCH -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v2/accounts/123/team/groups/g982734' \
    --data-binary '{"name": "Other Group"}'
  • RequestToggle
  • Headers

    Content-Type: application/json

    Body

    {
      "name": "Other Group"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

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

Delete a Group 

Delete a groupDELETE /accounts/{account_id}/team/groups/{group_id}

Example request:

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

Membership 

Membership objects represent the membership of a user or group in another group. They have the following attributes:

  • id (read-only) The ID of the membership object, used to reference it in other requests.

  • type (read-only) Always membership.

  • api (read-only) Always team.

  • member (non-editable) The object that is a member of the Group, either a User or a Group.

  • group (non-editable) The group the member is a part of.

  • role The role of the member in the group, default: member.

Services currently supported are:

  • gdrive

  • onedrivebiz

  • sharepoint

Create Membership 

Create MembershipPOST /accounts/{account_id}/team/memberships

To create a new Membership, performa a POST request with a json object containing the member, target group, and the role.

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json'
    'https://api.kloudless.com/v2/accounts/123/team/memberships' \
    --data-binary '{
        "role": "member",
        "group": {"id": "g982734",  "type": "group"},
        "member": {"id": "uZGVycEBtZXJwLmNvbQo", "type": "user"}
        }'
  • RequestToggle
  • Headers

    Content-Type: application/json

    Body

    {
      "role": "member",
      "group": {
        "id": "g982734",
        "type": "group"
      },
      "member": {
        "id": "uZGVycEBtZXJwLmNvbQo",
        "type": "user"
      }
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "id": "mbWVycAo=",
        "type": "membership",
        "role": "member",
        "api": "team",
        "group": {
            "id": "g982734",
            "name": "Test Group",
            "type": "group",
            "api": "team",
        },
        "member": {
            "id": "uZGVycEBtZXJwLmNvbQo=",
            "id_type": "default",
            "name": "Jane Doe",
            "email": "user@test.com",
            "type": "user",
            "api": "team",
            "ids" {
                "default": "uZGVycEBtZXJwLmNvbQo=",
                "team": "t3141592"
            }
        }
    }

Update Membership 

Update MembershipPATCH /accounts/{account_id}/team/memberships/{membership_id}

To update a membership, a PATCH request can be performed. Any writable attributes can be included in the request body.

Example request:

curl -XPATCH -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json'
    'https://api.kloudless.com/v2/accounts/123/team/memberships/mbWVycAo=' \
    --data-binary '{ "role": "admin" }'
  • RequestToggle
  • Headers

    Content-Type: application/json

    Body

    {
        "role": "admin",
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "id": "mbWVycAo=",
        "type": "membership",
        "role": "admin",
        "api": "team",
        "group": {
            "id": "g982734",
            "name": "Test Group",
            "type": "group",
            "api": "team",
        },
        "member": {
            "id": "uZGVycEBtZXJwLmNvbQo=",
            "id_type": "default",
            "name": "Jane Doe",
            "email": "user@test.com",
            "type": "user",
            "api": "team",
            "ids" {
                "default": "uZGVycEBtZXJwLmNvbQo=",
                "team": "t3141592"
            }
        }
    }

Delete Membership 

Delete MembershipDELETE /accounts/{account_id}/team/memberships/{membership_id}

Example request:

curl -XDELETE -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/accounts/123/team/memberships/mbWVycAo='
  • Response  204