Organizations

When you create an account, a personal organization is automatically created for you. An organization is a self-contained project environment that will house your digital twins and any associated information.

You can create multiple organizations to organize your work, and invite users to collaborate with you on your projects.

Adding users to an organization gives them access to any twins, marketplaces, assets and tasks contained within the context of an organization.

Every action you take on the platform or with the API is within the context of an organization. You will need to pass the organization id in the headers of every request.

Create a New Organization

Let’s create a new organization.

curl --location --request POST '<API_URL>/app/organizations/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Token <ACCESS_TOKEN>'
--data-raw '{"data": {"type": "organizations", "attributes":{"name": "<YOUR ORG NAME>"}}}'

As shown in the above example, we’ve added additional information to our request.

Every request and action needs to be performed within the context of an organization. This information is contained with the custom ‘X-Organization’ header key. The value of the key is the ID of the organization within which you are working.

We also specify the content type to each request. This is best practice every time we create (POST) or update (PUT/PATCH) a resource.

Creating an organization takes two fields; name and description (optional). We also declare the object type in the type key.

{
    "data": {
        "type": "organizations",
        "id": "<ORG_ID>",
        "attributes": {
            "created": "<TIMESTAMP OF DATE CREATED>",
            "modified": "<TIMESTAMP OF DATE LAST MODIFIED>",
            "name": "<ORG_NAME>",
            "is-active": true,
            "features": [],
            "allow-auto-join": true
        }
    }
}

List All Your Active Organizations

You can access information about all the organizations you have created, or have access to with the following command:

curl --location --request GET '<API_URL>/app/organizations/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Authorization: Token <ACCESS_TOKEN>'

As shown in the example, every request or action is performed within the context of an organization. This information is sent within the header.

You will be presented with a list of all your organizations:

{
    "data": [
        {
            "type": "organizations",
            "id": "<YOUR_ORG_ID>",
            "attributes": {
                "created": "<TIMESTAMP OF DATE RESOURCE CREATED>",
                "modified": "<TIMESTAMP OF DATE RESOURCE MODIFIED>",
                "name": "<NAME OF ORG>",
                "is-active": true,
                "features": [],
                "allow-auto-join": true
            }
        },
        {
            "type": "organizations",
            "id": "<YOUR_ORG_ID>",
            "attributes": {
                "created": "<TIMESTAMP OF DATE RESOURCE CREATED>",
                "modified": "<TIMESTAMP OF DATE RESOURCE MODIFIED>",
                "name": "<NAME OF ORG>",
                "is-active": true,
                "features": [],
                "allow-auto-join": true
            }
        },    ]
}

List Details of a Specific Organization

You can obtain the details of a specific organization using the following:

curl --location --request GET '<API_URL>/app/organizations/<ORG_ID>/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Authorization: Token <ACCESS_TOKEN>'

This will return the following details

{
    "data": {
        "type": "organizations",
        "id": "<ORG_ID>",
        "attributes": {
            "created": "<TIMESTAMP OF DATE CREATED>",
            "modified": "<TIMESTAMP OF DATE LAST MODIFIED>",
            "name": "<ORG_NAME>",
            "is-active": true,
            "features": [],
            "allow-auto-join": true
        }
    }
}

Switch Organizations

As mentioned in the start, we are always working in the context of an organization. When you first created an account, a personal organization was automatically created for you and designated as your default organization.

You can change this setting and switch the context of your working organization by the following:

curl --location --request POST '<API_URL>/me/organization_switch/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Token <ACCESS_TOKEN>'
--data-raw '{"organization_id": "<TARGET_ORG_ID>"}}'

In the data field, we pass details for the target organization (<TARGET_ORG-ID>, which is the ID of the organization you want to switch to.

You will receive the following upon a successful request:

{
    "id": "<NEW_ORG_ID>",
    "name": "name",
    "allow_auto_join": true,
    "features": [],
    "subscription_info": {}
}

Update Details of a Specific Organization

In this example let’s change the name of the organization

curl --location --request PATCH '<API_URL>/app/organizations/<ORG_ID>/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Token <ACCESS_TOKEN>'
--data-raw '{"data": {"type": "organizations", "id": "<ORG_ID>", "attributes":{"name": "<NEW_ORG_NAME>"}}}'

This time, we include the URL of the specific organization we wish to modify in the target url. We also need to pass the target url in the data fields, as well as include the new name of the organization in the data attributes of this PATCH request.

When you have successfully updated the name, you will receive the following confirmation:

{
    "data": {
        "type": "organizations",
        "id": "<ORG_ID>",
        "attributes": {
            "created": "<TIMESTAMP OF DATE CREATED>",
            "modified": "<TIMESTAMP OF DATE LAST MODIFIED>",
            "name": "<NEW_ORG_NAME>",
            "is-active": true,
            "features": [],
            "allow-auto-join": true
        }
    }
}

Delete an Organization

Deleting an organization will remove any of its contained data including twins, tasks, assets and information saved and stored within that organization.

Only users with administrator privileges can delete organizations.

NOTE: If you are going to delete an organization, please ensure you have at least one active organization remaining.

The following command will delete an organization:

curl --location --request POST '<API_URL>/app/organizations/<ORG_ID>/delete_organization/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Token <ACCESS_TOKEN>' \

As displayed, it’s important to include the ID of the organization to be deleted in the URL.

When an organization is deleted successfully, you will receive the following message:

{
    "data": {
        "status_code": 200,
        "detail": "Organization was deleted"
    }
}