Group Users

A GroupUser is a record about membership of a User within a Group.

Creating GroupUsers

GroupUsers can be created via the normal create action. When using the update action, if the GroupUser record does not exist for the given user/group IDs it will be created.

List Group Users

Endpoint

GET/group_users

Return Object

GroupUser[]

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

ParameterDescription
group_id
int64		Group ID. If provided, returns memberships of this group. Requires a Site Administrator, a Read-only Administrator, a Workspace Administrator for the group's workspace, or a Group Administrator of this group.
user_id
int64		User ID. If provided, will return group_users of this user.

Can be set by: Site Administrator; Read-only Administrator; Workspace Administrator.

Additional Arguments

Example Request

curl "https://app.files.com/api/rest/v1/group_users.json?group_id=1&user_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "group_name": "My Group",
    "group_id": 1,
    "user_id": 1,
    "admin": true,
    "username": "example"
  }
]

Create Group User

Endpoint

POST/group_users

Return Object

GroupUser

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator, a Workspace Administrator for the relevant workspace, or a Group Administrator for the relevant group.

Request Parameters

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

ParameterDescription
group_id
int64
Required		Group ID to add user to.

Can be set by: Site Administrator; Workspace Administrator; Group Administrator.
user_id
int64
Required		User ID to add to group.

Can be set by: Site Administrator; Workspace Administrator; Group Administrator.
admin
boolean		Is the user a group administrator?

Can be set by: Site Administrator; Workspace Administrator.

Example Request

curl https://app.files.com/api/rest/v1/group_users.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"group_id":1,"user_id":1,"admin":false}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "group_name": "My Group",
  "group_id": 1,
  "user_id": 1,
  "admin": true,
  "username": "example"
}

Update Group User

Endpoint

PATCH/group_users/{id}

Return Object

GroupUser

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator, a Workspace Administrator for the relevant workspace, or a Group Administrator for the relevant group.

Request Parameters

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

ParameterDescription
id
int64
Required		Group User ID.

Can be set by: Site Administrator; Workspace Administrator; Group Administrator.
group_id
int64
Required		Group ID to add user to.

Can be set by: Site Administrator; Workspace Administrator; Group Administrator.
user_id
int64
Required		User ID to add to group.

Can be set by: Site Administrator; Workspace Administrator; Group Administrator.
admin
boolean		Is the user a group administrator?

Can be set by: Site Administrator; Workspace Administrator.

Example Request

curl https://app.files.com/api/rest/v1/group_users/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"group_id":1,"user_id":1,"admin":false}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "group_name": "My Group",
  "group_id": 1,
  "user_id": 1,
  "admin": true,
  "username": "example"
}

Delete Group User

Endpoint

DELETE/group_users/{id}

Return Object

No return value.

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator, a Workspace Administrator for the relevant workspace, or a Group Administrator for the relevant group.

Request Parameters

ParameterDescription
id
int64
Required		Group User ID.
group_id
int64
Required		Group ID from which to remove user.
user_id
int64
Required		User ID to remove from group.

Example Request

curl "https://app.files.com/api/rest/v1/group_users/{id}.json?group_id=1&user_id=1" \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

The GroupUser Object

Some of the endpoints above return a GroupUser object. The attributes of this object are listed below.

AttributeDescription
group_name
string		Group name
group_id
int64		Group ID
user_id
int64		User ID
admin
boolean		Is this user an administrator of this group?
username
string		Username of the user

Example GroupUser Object

{
  "group_name": "My Group",
  "group_id": 1,
  "user_id": 1,
  "admin": true,
  "username": "example"
}