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.

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.
  • 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 (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.

• 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.

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

• raw (optional) Underlying object retrieved from the service.

List Users 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/accounts/123/team/users'

Create User 

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -H 'X-Kloudless-Raw-Data: true' \
    'https://api.kloudless.com/v2/accounts/123/team/users' \
    --data-binary '{
        "name": "Test User",
        "email": "user@test.com",
        "raw": {
            "object": {
                "companyName": "kloudless",
                "jobTitle": "developer"
            }
        }
    }'

Retrieve a User 

curl -H 'Authorization: Bearer [TOKEN]' \
     -H 'X-Kloudless-Raw-Data: true' \
    'https://api.kloudless.com/v2/accounts/123/team/users/u4806226'

List a User's Group Memberships 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/accounts/123/team/users/u4806226/memberships'

Update User 

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

Delete a User 

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

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.

• raw (optional) Underlying object retrieved from the service.

• 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 

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

Create Group 

curl -XPOST  -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -H 'X-Kloudless-Raw-Data: true' \
    'https://api.kloudless.com/v2/accounts/123/team/groups/' \
    --data-binary '{
        "name": "Test Group",
        "raw": {
            "object": {
                "mailNickname": "testgroup"
            }
        }
    }'

Retrieve a Group 

curl -H 'Authorization: Bearer [TOKEN]' \
     -H 'X-Kloudless-Raw-Data: true' \
    'https://api.kloudless.com/v2/accounts/123/team/groups/g982734'

List a Group's Members 

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

Update Group 

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

Delete a Group 

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

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 

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

Update Membership 

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

Delete Membership 

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