puter/doc/api/group.md

Group Endpoints

POST /group/create (auth required)

Description

Creates a group and returns a UID (UUID formatted). Groups do not have names, or any other descriptive attributes. Instead they are always identified with a UUID, and they have a metadata property.

The metadata property will always be given back to the client in the same way it was provided. The extra property, also an object, may be changed by the backend. The behavior of setting any property on extra is currently undefined as all properties are reserved for future use.

Parameters

• metadata: - optional
  • accepts: object
  • description: arbitrary metadata to describe the group
• extra: - optional
  • accepts: object
  • description: extra parameters (server may change these)

Request Example

await fetch(`${window.api_origin}/group/create`, {
  "headers": {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${puter.authToken}`,
  },
  "body": JSON.stringify({
    metadata: { title: 'Some Title' }
  }),
  "method": "POST",
});

// { uid: '9c644a1c-3e43-4df4-ab67-de5b68b235b6' }

Response Example

{
    "uid": "9c644a1c-3e43-4df4-ab67-de5b68b235b6"
}

POST /group/add-users

Description

Adds one or more users to a group

Parameters

• uid: - required
  • accepts: string UUID of an existing group
• users: Array<string> usernames of users to add to the group

Request Example

await fetch(`${window.api_origin}/group/add-users`, {
  "headers": {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${puter.authToken}`,
  },
  "body": JSON.stringify({
      uid: '9c644a1c-3e43-4df4-ab67-de5b68b235b6',
      users: ['first_user', 'second_user'],
  }),
  "method": "POST",
});

POST /group/remove-users

Description

Remove one or more users from a group

Parameters

• uid: - required
  • accepts: string UUID of an existing group
• users: Array<string> usernames of users to remove from the group

Request Example

await fetch(`${window.api_origin}/group/add-users`, {
  "headers": {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${puter.authToken}`,
  },
  "body": JSON.stringify({
      uid: '9c644a1c-3e43-4df4-ab67-de5b68b235b6',
      users: ['first_user', 'second_user'],
  }),
  "method": "POST",
});

GET /group/list

Description

List groups associated with the current user

Parameters

none

Response Example

{
    "owned_groups": [
        {
            "uid": "c3bd4047-fc65-4da8-9363-e52195890de4",
            "metadata": {},
            "members": [
                "default_user"
            ]
        }
    ],
    "in_groups": [
        {
            "uid": "c3bd4047-fc65-4da8-9363-e52195890de4",
            "metadata": {},
            "members": [
                "default_user"
            ]
        }
    ]
}

Group Permission Endpoints

POST /grant-user-group

Grant permission from the current user to a group. This creates an association between the user and the group for this permission; the group will only have the permission effectively while the user who granted permission has the permission.

Parameters

• group_uid: - required
  • accepts: string UUID of an existing group
• permission: - required
  • accepts: string A permission string

Request Example

await fetch("http://puter.localhost:4100/auth/grant-user-group", {
  "headers": {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${puter.authToken}`,
  },
  "body": JSON.stringify({
      group_uid: '9c644a1c-3e43-4df4-ab67-de5b68b235b6',
      permission: 'fs:/someuser/somedir/somefile:read'
  }),
  "method": "POST",
});

POST /revoke-user-group

Revoke permission granted from the current user to a group.

Parameters

• group_uid: - required
  • accepts: string UUID of an existing group
• permission: - required
  • accepts: string A permission string

Request Example

await fetch("http://puter.localhost:4100/auth/grant-user-group", {
  "headers": {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${puter.authToken}`,
  },
  "body": JSON.stringify({
      group_uid: '9c644a1c-3e43-4df4-ab67-de5b68b235b6',
      permission: 'fs:/someuser/somedir/somefile:read'
  }),
  "method": "POST",
});

• TODO figure out how to manage documentation that could reasonably show up in two files. For example: this is a group endpoint as well as a permission system endpoint. (architecturally it's a permission system endpoint, and the permissions feature depends on the groups feature; at least until a time when PermissionService is refactored so a service like GroupService can mutate the permission check sequences)