Create an Organization

This section describes how to create an Organization on your self-hosted instance of Parsec Server.

Before starting

The process of creating an Organization in Parsec involves the following steps:

Create an organization: Create an organization with a valid name (as described in this section) and obtain a bootstrap link to create the first user.
Set up Sequester service (optional): The sequester service allows to securely recover all data from an Organization. It can only be activated during the Organization bootstrap and not afterwards.
Bootstrap the organization: Bootstrapping is the process of creating the first user for the Organization. This can be done by anyone having the bootstrap link.

Important

The first user is trusted by default (no code exchange is required) and is responsible for inviting subsequent users and therefore building trust via the steps to join an Organization.

The following diagram summarizes the process:

sequenceDiagram actor Admin as Server Admin participant Parsec actor Alice Admin->>Parsec: Create Organization
with a valid name Parsec-->>Admin: bootstrap link opt Admin->>Parsec: Set up Sequester Service end alt Server Admin is part of the Organization Admin->>Parsec: Use bootstrap link
to create first user else Server Admin is not part of the Organization Admin->>Alice: Send bootstrap link Alice->>Parsec: Use bootstrap link
to create first user end

Note

If you enabled spontaneous bootstrap on your Parsec Server anyone can create an Organization. This is done directly from the Parsec client application by specifying your server URL and following steps in Parsec to create the first user.

The sequester service cannot be set up for Organizations created in this way.

Refer to Create an organization on my own Parsec server.

Create an Organization

Custom TLS certificates

If you’ve used custom TLS certificates to deploy Parsec Server (recommended only for testing purposes) you will need to provide the trusted CA (both to Parsec CLI and Parsec app). You can do this by exporting the SSL_CAFILE before proceeding:

export SSL_CAFILE=$PWD/custom-ca.crt

Define required information

Define SERVER_ADDR to your server address and ORGANIZATION_NAME to the desired name for the organization (see About Organization Names).
```
SERVER_ADDR=parsec3://127.0.0.1:6777
ORGANIZATION_NAME=MyOrganization
```
You can also specify this information manually in each command.
Define Administration token for the CLI

If you followed the instructions in Server Deployment you can load the corresponding file before calling the CLI:
```
set -a && source parsec-admin-token.env && set +a
```
Otherwise, create this file now with the PARSEC_ADMINISTRATION_TOKEN variable and load it so you can use it below.
Create the organization

This can be done either with Parsec CLI or via the REST Administration API.
Using Parsec CLI

To create an organization with Parsec CLI you will use the following command:
```
parsec-cli organization create --addr $SERVER_ADDR $ORGANIZATION_NAME
```
Using the REST Administration API

To create an organization with the REST Administration API you need to make a POST request to the administration/organizations endpoint.

Here is an example of how to run the query using curl and jq:
```
$ DATA=$(jq -n --arg organization_id "$ORGANIZATION_NAME" '$ARGS.named')
$ curl ${SERVER_ADDR}/administration/organizations \
-H "Authorization: Bearer $PARSEC_ADMINISTRATION_TOKEN" \
--request POST --data $DATA | jq
```
Save the Bootstrap link or bootstrap url displayed in either case before proceeding to bootstrap.
Bootstrap the Organization
1. Start Parsec client application (web or desktop)
2. Select Create or join ‣ Join`
3. Paste the bootstrap link from previous step
4. Follow the instructions to create the first user of the Organization.

Configure an Organization

Possible configuration options are:

user_profile_outsider_allowed (default: true)

To allow or disallow users with External profile. See User Profiles.

active_users_limit (default: none)

The maximum number of active (i.e. non-revoked) users. By default, the number of active users is unlimited. The limit does not apply to users with External profiles (which are always unlimited).

realm_minimum_archiving_period_before_deletion (default: 2592000, 30 days)

When a user deletes a workspace, this is the minimum amount of time (in seconds) that must pass before the workspace is effectively deleted.

tos (default: none)

This option allows you to specify a custom set of ToS that users will need to accept in order to connect to the organization. This is specified as a JSON object, with a language code as key, and a link to the term of services in that language as value. For example:

{
  "fr": "link-to-tos-in-french.pdf",
  "en": "link-to-tos-in-english.pdf"
}

They can be set using the REST Administration API, either during organization creation (step 3 above) or later with a PATCH request.

Here is an example using curl and jq:

$ DATA=$(jq -n \
  --arg organization_id $ORGANIZATION_NAME \
  --argjson user_profile_outsider_allowed false \
  --argjson active_users_limit 5 \
  --argjson tos "{\"fr\":\"$SERVER_ADDR/tos-FR\"}" \
  --argjson realm_minimum_archiving_period_before_deletion 864000 \
  '$ARGS.named' -c )

$ curl ${SERVER_ADDR}/administration/organizations/$ORGANIZATION_NAME \
  -H "Authorization: Bearer $PARSEC_ADMINISTRATION_TOKEN" \
  --request PATCH --json $DATA | jq