Developer Documentation / Tutorials / Workspaces / Manage Workspaces

Manage Workspaces

💡 3 min read

Learn how to create a Workspace and add a user to it

Workspaces help keep your work organized. Once a workspace has users, you can share content that you've uploaded with them.

You can see the current sharing status on any resource by querying the @sharing endpoint.

You can always check the results of the API calls on your Onna account.

# Before you begin

Make sure that you're authenticated with your Onna instance.

# Create a Workspace

You'll create a workspace, which for us is another content type created with a POST.

First, lets see if there are any workspaces associated with our user.

headers = {'Accept': 'application/json', 'Authorization': "Bearer {}".format(jwt_token)}
resp = requests.get(f'{base_url}/api/{container}/{account}/@workspaces', headers=headers)
print(f"Workspaces: {resp.json()}")

1
2
3

Unless you've already created a workspace either through the Web interface or the API, the response is an empty array.

Now, you can create a new workspace and store it's uid in a variable workspace_uid.

workspace_uid = None
payload = {
    "@type": "Workspace",
    "title": "Legal"
}
resp = requests.post(f"{base_url}/api/{container}/{account}/workspaces", headers=headers, data=json.dumps(payload))
workspace_uid = resp.json()['@uid']
print(resp.json())

1
2
3
4
5
6
7
8

With that POST, you created a workspace named "Legal".

The returned values include the @id combined with other metadata such as creation_date and the owners.

In subsequent calls, you'll refer to this workspace by its @uid, such as when you add users to this workspace.

You'll save the @uid value in a variable to use when you add a user to the workspace.

# Add a user to a Workspace

There are four roles a user can have when added to a workspace.

The role is set when the user is added to the workspace.

To add a user to a workspace, you'll do a POST to the workspace URLs @sharing endpoint.

The permissions that a user can have in a workspace are as follows:

For additional information on the roles and permissions used in Onna, please see Guillotina developer documentation (opens new window)

Role	Description
guillotina.Owner	Can Invite Users to the Workspace and Add Datasources
guillotina.Editor	Can Add Datasources and Edit the Workspace, Datasources and Files
onna.Contributor	Can Add Datasources and Files
guillotina.Reader	Can View Files in the Workspace

payload = {
"prinrole": [{
        "setting": "Allow",
        "principal": "user@domain.com",
        "role": "onna.Contributor"
    }
],
"magic_url": true,
"notify": true,
"notify_message": ""
}

resp = requests.post(f"{base_url}/api/{container}/{account}/workspaces/{workspace_uid}/@sharing",
                     headers=headers,
                     data=json.dumps(payload)
                    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

The response JSON should be a 200 with an empty body.

This also applies to adding User Groups to a workspace, together with adding multiple users/groups at once.

{
"prinrole": [{
        "setting": "Allow",
        "principal": "7cf46566-c4db-11e9-b7a7-921bb8ebe70b",
        "role": "guillotina.Editor"
    }, {
        "setting": "Allow",
        "principal": "user@domain.com",
        "role": "guillotina.Editor"
    }
],
"magic_url": true,
"notify": true,
"notify_message": ""
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Above, the first principal is the uid of a group of users. The second principal value is another user.

# Remove a user from a Workspace

In case you need to remove a user from a workspace, that is done through the same endpoint.

payload = {
"prinrole": [{
        "setting": "Unset",
        "principal": "user1@domain.com",
        "role": "onna.Contributor"
    }, {
        "setting": "Unset",
        "principal": "user2@domain.com",
        "role": "guillotina.Editor"
    }
],
"notify": false
}

resp = requests.post(f"{base_url}/api/{container}/{account}/workspaces/{workspace_uid}/@sharing",
                     headers=headers,
                     data=json.dumps(payload)
                    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

It is important to note that the role you are removing needs to be the role that the user had.

# Recap

You created a new workspace, and added a user to it.

← Try the API with Postman Datasource sync types and statuses →