• Register

Group Management API

The Group Management API allows you to list the groups in your domain, show the details of an individual group, manage group membership, create new groups, rename groups, and delete groups. This API is designed to comply with SCIM 1.1

Note that the user and group endpoints are v2, unlike the other endpoints within the Egnyte API.

List Groups

This endpoint is used to list all the groups in your domain.  Note that this returns only your custom domains.  Egnyte default groups (i.e. 'All Power Users', 'All Standard Users and Power Users', and 'All Standard Users') are not returned.

GET/pubapi/v2/groups

Request Examples

GET /pubapi/v2/groups HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
https://apidemo.egnyte.com/pubapi/v2/groups
require 'egnyte'
session = Egnyte::Session.new({domain:'apidemo', access_token:'68zc95e3xv954u6k3hbnma3q'}, :password)
client = Egnyte::Client.new(session)

# Call the endpoint and save result to a variable
groups = client.groups

# Or, if you want to call the endpoint without a client.
# groups = Egnyte::Group.all(session)

Sample Response Body

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "totalResults":3,
  "itemsPerPage":3,
  "startIndex":1,
  "resources":[{
    "id":"8b9dd5aa-40ab-4a43-9b76-f55a412c8a6a",
    "displayName":"IT"
  },{
    "id":"d5ea2e76-63e4-4b47-92af-0d7ba6972e3c",
    "displayName":"Finance"
  },{
    "id":"a1004249-5e29-438f-ad72-b4e90af14ee7",
    "displayName":"Sales"
  }]
}

Request Parameters

Parameter Description Required
startIndex The 1-based index of the initial record being requested (Integer ≥ 1). No
count The number of entries per page (min 1, max 100) No
filter

Allows you to request a subset of groups. These terms are not case sensitive. For example, the following commands could be used to find a group named Accounting:

  • filter=displayName eq "accounting" (for equals "accounting")
  • filter=displayname co "ccou" (for contains the letters "ccou")
  • filter=displayname sw "acc" (for starts with "acc")

Note: if you have trouble with these filters, please make sure you are URL encoding the spaces.

 No

Response Parameters

Element Description
itemsPerPage The number of results returned.
totalResults The total number of results matching the query.
startIndex The 1-based index of the first result in the current set of results.
schemas The SCIM schema version of the response.
resources A JSON array that holds all of the group objects.
id The globally unique group ID.
displayName The name of the group.

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
STARTINDEX_WRONG_VALUE Start index parameter is less than 1 400 Make sure you are using an integer value of 1 or more.

Show Single Group

This endpoint is used to see which users are in the group and view group attributes.

GET/pubapi/v2/groups/{group_id}

Request Examples

GET /pubapi/v2/groups/e085cf02-0625-459b-b6f9-fa4dd92d908d HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
https://apidemo.egnyte.com/pubapi/v2/groups/e085cf02-0625-459b-b6f9-fa4dd92d908d
require 'egnyte'
session = Egnyte::Session.new({domain:'apidemo', access_token:'68zc95e3xv954u6k3hbnma3q'}, :password)
client = Egnyte::Client.new(session)

# Call the endpoint and save result to a variable
my_group = client.group("a1004249-5e29-438f-ad72-b4e90af14ee7")

# Or, if you want to call the endpoint without a client.
# my_group = Egnyte::Group.find(session, "a1004249-5e29-438f-ad72-b4e90af14ee7")

Sample Response Body

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id":"e3ba9d90-ebc7-483e-abaa-a84e92480c86",
  "displayName":"Finance",
  "members":[
    {
      "username":"test",
      "value":9967960066,
      "display":"Test User"
    },{
      "username":"jdoe",
      "value":9967960068,
      "display":"John Doe"
    },{
      "username":"jadoe",
      "value":9967960069,
      "display":"Jane Doe"
    }
  ]
}

Response Parameters

Element Description
schemas The SCIM schema version of the response.
id The globally unique group ID.
displayName The name of the group.
members A JSON array containing all users in the group.
username The username of a group member.
value The globally unique id of a group member.
display The display name of a group member.

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
GROUP_NOT_FOUND group with resource id (SPECIFIED_GROUP_ID) not found 404 You may have used an invalid group ID or that group may have already been deleted.

Create a Group

POST /pubapi/v2/groups
POST /pubapi/v2/groups HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
Content-Type: application/json
Content-Length: 85

{
  "displayName":"API Test",
  "members":[
    {"value":9967960068},
    {"value":9967960069}
  ]
}
curl -v --request POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
-H "Content-Type: application/json" \
--data '{"displayName":"API Test", "members":[{"value":9967960068},{"value":9967960069}]}' \
https://apidemo.egnyte.com/pubapi/v2/groups
require 'egnyte'
session = Egnyte::Session.new({domain:'apidemo', access_token:'68zc95e3xv954u6k3hbnma3q'}, :password)
client = Egnyte::Client.new(session)

# Call the endpoint and save result to a variable
my_group = client.create_group({displayName: "Test with members",members: [9967960066, 9967960068]})

# Or, if you want to call the endpoint without a client.
# my_group = Egnyte::Group.create(session, {displayName: "Test with members",members: [9967960066, 9967960068]})

Request Parameters

Parameter Description Required
displayName The name of the group. Yes
members A JSON array containing all users in the group. No
value The globally unique id of a group member. No

Sample Response Body

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id":"f9366462-7070-4adb-b866-9a953527507b",
  "displayName":"API Test",
  "members":[
  {
    "username":"jdoe",
    "value":9967960068,
    "display":"John Doe"
  },{
    "username":"jadoe",
    "value":9967960069,
    "display":"Jane Doe"
  }]
}

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
ERROR_DUPLICATE_GROUP_NAME Group already exists. 409 A group with same name already exists. You can find that group in the group listing endpoint or create a group with a different name.

Full Update to a Group

This endpoint is used to overwrite all of the attributes of a group. This is especially useful for making a change to settings that ensures all prior settings are removed.

PUT /pubapi/v2/groups/{group_id}
PUT /pubapi/v2/groups/a1004249-5e29-438f-ad72-b4e90af14ee7 HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
Content-Type: application/json
Content-Length: 87

{
  "displayName":"Engineering",
  "members":[
    {"value":9967960068},
    {"value":9967960069}
  ]
}
curl -v --request PUT -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
-H "Content-Type: application/json" --data '{"displayName":"Engineering", \
"members":[{"value":9967960068},{"value":9967960069}]}' \
https://apidemo.egnyte.com/pubapi/v2/groups/a1004249-5e29-438f-ad72-b4e90af14ee7
require 'egnyte'
            session = Egnyte::Session.new({domain:'apidemo', access_token:'68zc95e3xv954u6k3hbnma3q'}, :password)
client = Egnyte::Client.new(session)

# The Ruby API Client always does a full update of a group based on the object's parameters.
# In this example, I get an arbitrary group and change its name to "Example" and change group membership.
my_group = client.groups.first
my_group.name = "Example"
my_group.members = [client.users.first.id]
my_group.save

Request Parameters

Parameter Description Required
displayName The name of the group. Yes
members A JSON array containing all users in the group. No
value The globally unique id of a group member. No

Sample Response Body

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id":"a1004249-5e29-438f-ad72-b4e90af14ee7",
  "displayName":"Engineering",
  "members":[{
    "username":"jdoe",
    "value":9967960068,
    "display":"John Doe"
  },
  {
    "username":"jadoe",
    "value":9967960069,
    "display":"Jane Doe"
  }]
}

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
USER_NOT_FOUNDUSER_NOT_FOUND User (#) does not exist 400 You may have used an invalid user ID or that user may have already been deleted.
GROUP_NOT_FOUNDGROUP_NOT_FOUND group with resource id (SPECIFIED_GROUP_ID) not found 404 You may have used an invalid group ID or that group may have already been deleted.
ERROR_DUPLICATE_GROUP_NAMEERROR_DUPLICATE_GROUP_NAME Group already exists. 409 A group with same name already exists. You can find that group in the group listing endpoint or create a group with a different name.

Partial Update to a Group

This endpoint is used to update specific attributes of a group. This is especially useful for making incremental modifications to a folder.

PATCH /pubapi/v2/groups/{group_id}

Rename the group

PATCH /pubapi/v2/groups/a1004249-5e29-438f-ad72-b4e90af14ee7 HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
Content-Type: application/json
Content-Length: 23

{"displayName":"Sales"}
curl -v --request PATCH -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
-H "Content-Type: application/json" --data '{"displayName": "Sales"}' \
https://apidemo.egnyte.com/pubapi/v2/groups/a1004249-5e29-438f-ad72-b4e90af14ee7
require 'egnyte'
session = Egnyte::Session.new({domain:'apidemo', access_token:'68zc95e3xv954u6k3hbnma3q'}, :password)
client = Egnyte::Client.new(session)

# The Ruby API Client always does a full update of a group based on the object's parameters.
# In this example, I get an arbitrary group and change its name to "Example."
my_group = client.groups.first
my_group.name = "Example"
my_group.save

Add a user to the group

PATCH /pubapi/v2/groups HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
Content-Type: application/json
Content-Length: 34

{
  "members":[
    {"value":9967960066}
  ]
}
curl -v --request PATCH -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
-H "Content-Type: application/json" --data '{"members":[{"value":9967960066}]}' \
https://apidemo.egnyte.com/pubapi/v2/groups/a1004249-5e29-438f-ad72-b4e90af14ee7
require 'egnyte'
session = Egnyte::Session.new({domain:'apidemo', access_token:'68zc95e3xv954u6k3hbnma3q'}, :password)
client = Egnyte::Client.new(session)

# The Ruby API Client always does a full update of a group based on the object's parameters.
# In this example, I get an arbitrary group and an arbitrary user to it.
my_group = client.groups.first
my_group.members = [client.users.first.id]
my_group.save

Remove a user from the group

PATCH /pubapi/v2/groups HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
Content-Type: application/json
Content-Length: 34

{
  "members":[
    {
      "operation":"delete",
      "value":9967960066
    }
  ]
}
curl -v --request PATCH -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
-H "Content-Type: application/json" \
--data '{"members":[{"operation":"delete","value":9967960066}]}' \
https://apidemo.egnyte.com/pubapi/v2/groups/a1004249-5e29-438f-ad72-b4e90af14ee7
Element Description
displayName The name of the group.
members A JSON array containing all users in the group.
value The globally unique id of a group member.
members A JSON array containing all users being modified.
operation The action you wish to perform on a group. The only supported value is the "delete" action.

Sample Response Body

{
      "schemas":["urn:scim:schemas:core:1.0"],
      "id":"a1004249-5e29-438f-ad72-b4e90af14ee7",
      "displayName":"Example",
      "members":[
        {
          "username":"jdoe",
          "value":9967960068,
          "display":"John Doe"
        },
        {
          "username":"jadoe",
          "value":9967960069,
          "display":"Jane Doe"
        }
      ]
}

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
USER_NOT_FOUND User (#) does not exist 400 You may have used an invalid user ID or that user may have already been deleted.
GROUP_NOT_FOUND group with resource id (SPECIFIED_GROUP_ID) not found 404 You may have used an invalid group ID or that group may have already been deleted.
ERROR_DUPLICATE_GROUP_NAME Group already exists. 409 A group with same name already exists. You can find that group in the group listing endpoint or create a group with a different name.

Delete a Group

DELETE/pubapi/v2/groups/{group_id}

Request Examples

DELETE /pubapi/v2/groups/e085cf02-0625-459b-b6f9-fa4dd92d908d HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v --request DELETE -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
https://apidemo.egnyte.com/pubapi/v2/groups/e085cf02-0625-459b-b6f9-fa4dd92d908d
require 'egnyte'
session = Egnyte::Session.new({domain:'apidemo', access_token:'68zc95e3xv954u6k3hbnma3q'}, :password)
client = Egnyte::Client.new(session)

# In this example, I get an arbitrary group and delete it.
client.groups.first.delete

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
GROUP_NOT_FOUND group with resource id (SPECIFIED_GROUP_ID) not found 404 You may have used an invalid group ID or that group may have already been deleted.

version 20 as of 7 years ago by Grant Yang