Skip to content

Organizations

Please contact support at [email protected] if you would like to manage an organization. Tell us what you're doing, and select an organization name, title, description, email address, and url. We will then create your organization and make your account an admin of the organization. You will then be able to create new users in your org and generate a temporary authentication link for any user.

Source code in src/cocalc_api/org.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
class Organizations:

    def __init__(self, parent: "Hub"):
        self._parent = parent

    @api_method("org.getAll")
    def get_all(self) -> dict[str, Any]:
        """
        Get all organizations (site admins only).

        Returns:
            dict[str, Any]: Organization data.
        """
        ...  # pragma: no cover

    @api_method("org.create")
    def create(self, name: str) -> dict[str, Any]:
        """
        Create an organization (site admins only).

        Args:
            name (str): Name of the organization; must be globally unique,
                at most 39 characters, and CANNOT BE CHANGED.

        Returns:
            dict[str, Any]: Organization data.
        """
        ...  # pragma: no cover

    @api_method("org.get")
    def get(self, name: str) -> dict[str, Any]:
        """
        Get an organization.

        Args:
            name (str): Name of the organization.

        Returns:
            dict[str, Any]: Organization data.
        """
        ...  # pragma: no cover

    @api_method("org.set")
    def set(self,
            name: str,
            title: Optional[str] = None,
            description: Optional[str] = None,
            email_address: Optional[str] = None,
            link: Optional[str] = None) -> dict[str, Any]:
        """
        Set properties of an organization.

        Args:
            name (str): Name of the organization.
            title (Optional[str]): The title of the organization.
            description (Optional[str]): Description of the organization.
            email_address (Optional[str]): Email address to reach the organization
                (nothing to do with a cocalc account).
            link (Optional[str]): A website of the organization.
        """
        ...  # pragma: no cover

    @api_method("org.addAdmin")
    def add_admin(self, name: str, user: str) -> dict[str, Any]:
        """
        Make the user with given account_id or email an admin
        of the named organization.

        Args:
            name (str): name of the organization
            user (str): email or account_id
        """
        ...  # pragma: no cover

    @api_method("org.addUser")
    def add_user(self, name: str, user: str) -> dict[str, Any]:
        """
        Make the user with given account_id or email a member
        of the named organization. Only site admins can do this.
        If you are an org admin, instead use user to create
        new users in your organization, or contact support.

        Args:
            name (str): name of the organization
            user (str): email or account_id
        """
        ...  # pragma: no cover

    @api_method("org.createUser")
    def create_user(self,
                    name: str,
                    email: str,
                    firstName: Optional[str] = None,
                    lastName: Optional[str] = None,
                    password: Optional[str] = None) -> str:
        """
        Create a new cocalc account that is a member of the
        named organization.

        Args:
            name (str): name of the organization
            email (str): email address
            firstName (Optional[str]): optional first name of the user
            lastName (Optional[str]): optional last name of the user
            password (Optional[str]): optional password (will be randomized if
                not given; you can instead use create_token to grant temporary
                account access).

        Returns:
            str: account_id of the new user
        """
        ...  # pragma: no cover

    @api_method("org.createToken")
    def create_token(self, user: str) -> TokenType:
        """
        Create a token that provides temporary access to the given
        account.  You must be an admin for the org that the user
        belongs to or a site admin.

        Args:
            user (str): email address or account_id

        Returns:
            TokenType: token that grants temporary access

        Notes:
            The returned `TokenType` has the following fields:

            - `token` (str): The random token itself, which you may retain
              in case you want to explicitly expire it early.
            - `url` (str): The url that the user should visit to sign in as
              them.  You can also test out this url, since the token works
              multiple times.
        """
        ...  # pragma: no cover

    @api_method("org.expireToken")
    def expire_token(self, token: str) -> dict[str, Any]:
        """
        Immediately expire a token created using create_token.

        Args:
            token (str): a token
        """
        ...  # pragma: no cover

    @api_method("org.getUsers")
    def get_users(self, name: str) -> list[OrganizationUser]:  # type: ignore[empty-body]
        """
        Return list of all accounts that are members of the named organization.

        Args:
            name (str): name of the organization

        Returns:
            list[OrganizationUser]

        Notes:
            The returned `OrganizationUser` has the following fields:

            - `first_name` (str)
            - `last_name` (str)
            - `account_id` (str): a uuid
            - `email_address` (str)
        """
        ...  # pragma: no cover

    @api_method("org.removeUser")
    def remove_user(self, name: str, user: str) -> dict[str, Any]:
        """
        Remove a user from an organization.

        Args:
            name (str): name of the organization
            user (str): email or account_id
        """
        ...  # pragma: no cover

    @api_method("org.removeAdmin")
    def remove_admin(self, name: str, user: str) -> dict[str, Any]:
        """
        Remove an admin from an organization.

        Args:
            name (str): name of the organization
            user (str): email or account_id
        """
        ...  # pragma: no cover

    @api_method("org.message")
    def message(self, name: str, subject: str, body: str) -> dict[str, Any]:
        """
        Send a message from you to every account that is a member of
        the named organization.

        Args:
            name (str): name of the organization
            subject (str): plain text subject of the message
            body (str): markdown body of the message (math typesetting works)
        """
        ...  # pragma: no cover

add_admin(name, user)

Make the user with given account_id or email an admin of the named organization.

Parameters:

Name Type Description Default
name str

name of the organization

 required
user str

email or account_id

 required
Source code in src/cocalc_api/org.py 
71
72
73
74
75
76
77
78
79
80
81
@api_method("org.addAdmin")
def add_admin(self, name: str, user: str) -> dict[str, Any]:
    """
    Make the user with given account_id or email an admin
    of the named organization.

    Args:
        name (str): name of the organization
        user (str): email or account_id
    """
    ...  # pragma: no cover

add_user(name, user)

Make the user with given account_id or email a member of the named organization. Only site admins can do this. If you are an org admin, instead use user to create new users in your organization, or contact support.

Parameters:

Name Type Description Default
name str

name of the organization

 required
user str

email or account_id

 required
Source code in src/cocalc_api/org.py 
83
84
85
86
87
88
89
90
91
92
93
94
95
@api_method("org.addUser")
def add_user(self, name: str, user: str) -> dict[str, Any]:
    """
    Make the user with given account_id or email a member
    of the named organization. Only site admins can do this.
    If you are an org admin, instead use user to create
    new users in your organization, or contact support.

    Args:
        name (str): name of the organization
        user (str): email or account_id
    """
    ...  # pragma: no cover

create(name)

Create an organization (site admins only).

Parameters:

Name Type Description Default
name str

Name of the organization; must be globally unique, at most 39 characters, and CANNOT BE CHANGED.

 required

Returns:

Type Description
dict[str, Any]

dict[str, Any]: Organization data.
Source code in src/cocalc_api/org.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
@api_method("org.create")
def create(self, name: str) -> dict[str, Any]:
    """
    Create an organization (site admins only).

    Args:
        name (str): Name of the organization; must be globally unique,
            at most 39 characters, and CANNOT BE CHANGED.

    Returns:
        dict[str, Any]: Organization data.
    """
    ...  # pragma: no cover

create_token(user)

Create a token that provides temporary access to the given account. You must be an admin for the org that the user belongs to or a site admin.

Parameters:

Name Type Description Default
user str

email address or account_id

 required

Returns:

Name Type Description
TokenType TokenType

token that grants temporary access
Notes

The returned TokenType has the following fields:

  • token (str): The random token itself, which you may retain in case you want to explicitly expire it early.
  • url (str): The url that the user should visit to sign in as them. You can also test out this url, since the token works multiple times.
Source code in src/cocalc_api/org.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
@api_method("org.createToken")
def create_token(self, user: str) -> TokenType:
    """
    Create a token that provides temporary access to the given
    account.  You must be an admin for the org that the user
    belongs to or a site admin.

    Args:
        user (str): email address or account_id

    Returns:
        TokenType: token that grants temporary access

    Notes:
        The returned `TokenType` has the following fields:

        - `token` (str): The random token itself, which you may retain
          in case you want to explicitly expire it early.
        - `url` (str): The url that the user should visit to sign in as
          them.  You can also test out this url, since the token works
          multiple times.
    """
    ...  # pragma: no cover

create_user(name, email, firstName=None, lastName=None, password=None)

Create a new cocalc account that is a member of the named organization.

Parameters:

Name Type Description Default
name str

name of the organization

 required
email str

email address

 required
firstName Optional[str]

optional first name of the user

 None
lastName Optional[str]

optional last name of the user

 None
password Optional[str]

optional password (will be randomized if not given; you can instead use create_token to grant temporary account access).

 None

Returns:

Name Type Description
str str

account_id of the new user
Source code in src/cocalc_api/org.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@api_method("org.createUser")
def create_user(self,
                name: str,
                email: str,
                firstName: Optional[str] = None,
                lastName: Optional[str] = None,
                password: Optional[str] = None) -> str:
    """
    Create a new cocalc account that is a member of the
    named organization.

    Args:
        name (str): name of the organization
        email (str): email address
        firstName (Optional[str]): optional first name of the user
        lastName (Optional[str]): optional last name of the user
        password (Optional[str]): optional password (will be randomized if
            not given; you can instead use create_token to grant temporary
            account access).

    Returns:
        str: account_id of the new user
    """
    ...  # pragma: no cover

expire_token(token)

Immediately expire a token created using create_token.

Parameters:

Name Type Description Default
token str

a token

 required
Source code in src/cocalc_api/org.py 
146
147
148
149
150
151
152
153
154
@api_method("org.expireToken")
def expire_token(self, token: str) -> dict[str, Any]:
    """
    Immediately expire a token created using create_token.

    Args:
        token (str): a token
    """
    ...  # pragma: no cover

get(name)

Get an organization.

Parameters:

Name Type Description Default
name str

Name of the organization.

 required

Returns:

Type Description
dict[str, Any]

dict[str, Any]: Organization data.
Source code in src/cocalc_api/org.py 
38
39
40
41
42
43
44
45
46
47
48
49
@api_method("org.get")
def get(self, name: str) -> dict[str, Any]:
    """
    Get an organization.

    Args:
        name (str): Name of the organization.

    Returns:
        dict[str, Any]: Organization data.
    """
    ...  # pragma: no cover

get_all()

Get all organizations (site admins only).

Returns:

Type Description
dict[str, Any]

dict[str, Any]: Organization data.
Source code in src/cocalc_api/org.py 
14
15
16
17
18
19
20
21
22
@api_method("org.getAll")
def get_all(self) -> dict[str, Any]:
    """
    Get all organizations (site admins only).

    Returns:
        dict[str, Any]: Organization data.
    """
    ...  # pragma: no cover

get_users(name)

Return list of all accounts that are members of the named organization.

Parameters:

Name Type Description Default
name str

name of the organization

 required

Returns:

Type Description
list[OrganizationUser]

list[OrganizationUser]
Notes

The returned OrganizationUser has the following fields:

  • first_name (str)
  • last_name (str)
  • account_id (str): a uuid
  • email_address (str)
Source code in src/cocalc_api/org.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
@api_method("org.getUsers")
def get_users(self, name: str) -> list[OrganizationUser]:  # type: ignore[empty-body]
    """
    Return list of all accounts that are members of the named organization.

    Args:
        name (str): name of the organization

    Returns:
        list[OrganizationUser]

    Notes:
        The returned `OrganizationUser` has the following fields:

        - `first_name` (str)
        - `last_name` (str)
        - `account_id` (str): a uuid
        - `email_address` (str)
    """
    ...  # pragma: no cover

message(name, subject, body)

Send a message from you to every account that is a member of the named organization.

Parameters:

Name Type Description Default
name str

name of the organization

 required
subject str

plain text subject of the message

 required
body str

markdown body of the message (math typesetting works)

 required
Source code in src/cocalc_api/org.py 
199
200
201
202
203
204
205
206
207
208
209
210
@api_method("org.message")
def message(self, name: str, subject: str, body: str) -> dict[str, Any]:
    """
    Send a message from you to every account that is a member of
    the named organization.

    Args:
        name (str): name of the organization
        subject (str): plain text subject of the message
        body (str): markdown body of the message (math typesetting works)
    """
    ...  # pragma: no cover

remove_admin(name, user)

Remove an admin from an organization.

Parameters:

Name Type Description Default
name str

name of the organization

 required
user str

email or account_id

 required
Source code in src/cocalc_api/org.py 
188
189
190
191
192
193
194
195
196
197
@api_method("org.removeAdmin")
def remove_admin(self, name: str, user: str) -> dict[str, Any]:
    """
    Remove an admin from an organization.

    Args:
        name (str): name of the organization
        user (str): email or account_id
    """
    ...  # pragma: no cover

remove_user(name, user)

Remove a user from an organization.

Parameters:

Name Type Description Default
name str

name of the organization

 required
user str

email or account_id

 required
Source code in src/cocalc_api/org.py 
177
178
179
180
181
182
183
184
185
186
@api_method("org.removeUser")
def remove_user(self, name: str, user: str) -> dict[str, Any]:
    """
    Remove a user from an organization.

    Args:
        name (str): name of the organization
        user (str): email or account_id
    """
    ...  # pragma: no cover

set(name, title=None, description=None, email_address=None, link=None)

Set properties of an organization.

Parameters:

Name Type Description Default
name str

Name of the organization.

 required
title Optional[str]

The title of the organization.

 None
description Optional[str]

Description of the organization.

 None
email_address Optional[str]

Email address to reach the organization (nothing to do with a cocalc account).

 None
link Optional[str]

A website of the organization.

 None
Source code in src/cocalc_api/org.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@api_method("org.set")
def set(self,
        name: str,
        title: Optional[str] = None,
        description: Optional[str] = None,
        email_address: Optional[str] = None,
        link: Optional[str] = None) -> dict[str, Any]:
    """
    Set properties of an organization.

    Args:
        name (str): Name of the organization.
        title (Optional[str]): The title of the organization.
        description (Optional[str]): Description of the organization.
        email_address (Optional[str]): Email address to reach the organization
            (nothing to do with a cocalc account).
        link (Optional[str]): A website of the organization.
    """
    ...  # pragma: no cover