Workspace service#

This service provides information about workspaces. Workspaces provide access control boundaries. All resources in Nominal live within a workspace.

OpenAPI file: nominal.workspaces.v1.json

Endpoints#

Get default workspace#

GET /workspaces/v2/default-workspace

Gets the default workspace for the requesting user. If the user belongs to a single workspace, that workspace is returned. Otherwise, if the user’s organization has a default workspace and the user belongs to it, that will be returned.

Request

No parameters and no body.

Response

workspace Workspace

​

Fields of Workspace
id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string

​

org string

​

displayName string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol
one of icon, emoji, image

​

icon string

Workspace icon name (e.g. castle)

emoji string

Workspace emoji name (e.g. :castle:)

image string

Workspace image url (e.g. https://example.com/image.png)

settings WorkspaceSettings

​

Fields of WorkspaceSettings
refNames PreferredRefNameConfiguration

​

Fields of PreferredRefNameConfiguration
v1 array of RefNameAndType

​

Fields of RefNameAndType
name string

​

type DataSourceType

​

Values of DataSourceType
DATA_SOURCE_TYPE_UNSPECIFIED

​

DATASET

​

CONNECTION

​

VIDEO

​

SPATIAL

​

procedures ProcedureSettings

​

Fields of ProcedureSettings
v1 ProcedureSettingsV1

​

Fields of ProcedureSettingsV1
workspaceProcedures array of string

A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

Request

curl "https://api.gov.nominal.io/api/workspaces/v2/default-workspace" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/workspaces/v2/default-workspace",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/workspaces/v2/default-workspace",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/workspaces/v2/default-workspace",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "workspace": {
    "id": "<id>",
    "rid": "<rid>",
    "org": "<org>",
    "displayName": "<display name>",
    "symbol": {
      "icon": "<icon>"
    },
    "settings": {
      "refNames": {
        "v1": [
          {
            "name": "<name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "v1": {
          "workspaceProcedures": [
            "<workspace procedures>"
          ]
        }
      }
    }
  }
}

Get workspaces#

GET /workspaces/v2/workspaces

Gets all workspaces that the requesting user belongs to.

Query parameters

filterBySessionOrg boolean

When unset, defaults to true.

includeGuestWorkspaces boolean

When unset, defaults to false.

includeRoleBoundWorkspaces boolean

When unset, defaults to false. Also returns the session org’s workspaces where a role binding grants the caller workspace:view.

Response

workspaces array of Workspace

​

Fields of Workspace
id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string

​

org string

​

displayName string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol
one of icon, emoji, image

​

icon string

Workspace icon name (e.g. castle)

emoji string

Workspace emoji name (e.g. :castle:)

image string

Workspace image url (e.g. https://example.com/image.png)

settings WorkspaceSettings

​

Fields of WorkspaceSettings
refNames PreferredRefNameConfiguration

​

Fields of PreferredRefNameConfiguration
v1 array of RefNameAndType

​

Fields of RefNameAndType
name string

​

type DataSourceType

​

Values of DataSourceType
DATA_SOURCE_TYPE_UNSPECIFIED

​

DATASET

​

CONNECTION

​

VIDEO

​

SPATIAL

​

procedures ProcedureSettings

​

Fields of ProcedureSettings
v1 ProcedureSettingsV1

​

Fields of ProcedureSettingsV1
workspaceProcedures array of string

A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

Request

curl "https://api.gov.nominal.io/api/workspaces/v2/workspaces" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/workspaces/v2/workspaces",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "workspaces": [
    {
      "id": "<id>",
      "rid": "<rid>",
      "org": "<org>",
      "displayName": "<display name>",
      "symbol": {
        "icon": "<icon>"
      },
      "settings": {
        "refNames": {
          "v1": [
            {
              "name": "<name>",
              "type": "DATASET"
            }
          ]
        },
        "procedures": {
          "v1": {
            "workspaceProcedures": [
              "<workspace procedures>"
            ]
          }
        }
      }
    }
  ]
}

Update workspace#

PUT /workspaces/v2/workspaces/{rid}

Updates the settings of the workspace with the specified WorkspaceRid.

Path parameters

rid string required

​

Body

request UpdateWorkspaceRequest

​

Fields of UpdateWorkspaceRequest
displayName UpdateOrRemoveWorkspaceDisplayName

​

Fields of UpdateOrRemoveWorkspaceDisplayName
one of displayName, removeType required

​

displayName string

​

removeType RemoveType

​

symbol UpdateOrRemoveWorkspaceSymbol

​

Fields of UpdateOrRemoveWorkspaceSymbol
one of symbol, removeType required

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol
one of icon, emoji, image required

​

icon string

Workspace icon name (e.g. castle)

emoji string

Workspace emoji name (e.g. :castle:)

image string

Workspace image url (e.g. https://example.com/image.png)

removeType RemoveType

​

settings WorkspaceSettings

Excluded fields in the settings update will be ignored.

Fields of WorkspaceSettings
refNames PreferredRefNameConfiguration

​

Fields of PreferredRefNameConfiguration
v1 array of RefNameAndType

​

Fields of RefNameAndType
name string

​

type DataSourceType

​

Values of DataSourceType
DATA_SOURCE_TYPE_UNSPECIFIED

​

DATASET

​

CONNECTION

​

VIDEO

​

SPATIAL

​

procedures ProcedureSettings

​

Fields of ProcedureSettings
v1 ProcedureSettingsV1

​

Fields of ProcedureSettingsV1
workspaceProcedures array of string

A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

Response

workspace Workspace

​

Fields of Workspace
id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string

​

org string

​

displayName string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol
one of icon, emoji, image

​

icon string

Workspace icon name (e.g. castle)

emoji string

Workspace emoji name (e.g. :castle:)

image string

Workspace image url (e.g. https://example.com/image.png)

settings WorkspaceSettings

​

Fields of WorkspaceSettings
refNames PreferredRefNameConfiguration

​

Fields of PreferredRefNameConfiguration
v1 array of RefNameAndType

​

Fields of RefNameAndType
name string

​

type DataSourceType

​

Values of DataSourceType
DATA_SOURCE_TYPE_UNSPECIFIED

​

DATASET

​

CONNECTION

​

VIDEO

​

SPATIAL

​

procedures ProcedureSettings

​

Fields of ProcedureSettings
v1 ProcedureSettingsV1

​

Fields of ProcedureSettingsV1
workspaceProcedures array of string

A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

Request

curl -X PUT "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "request": {
    "displayName": {
      "displayName": "<display name>"
    },
    "symbol": {
      "symbol": {
        "icon": "<icon>"
      }
    },
    "settings": {
      "refNames": {
        "v1": [
          {
            "name": "<name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "v1": {
          "workspaceProcedures": [
            "<workspace procedures>"
          ]
        }
      }
    }
  }
}'

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "request": {
            "displayName": {"displayName": "<display name>"},
            "symbol": {"symbol": {"icon": "<icon>"}},
            "settings": {
                "refNames": {"v1": [{"name": "<name>", "type": "DATASET"}]},
                "procedures": {
                    "v1": {"workspaceProcedures": ["<workspace procedures>"]},
                },
            },
        },
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "request": {
            "displayName": {"displayName": "<display name>"},
            "symbol": {"symbol": {"icon": "<icon>"}},
            "settings": {
                "refNames": {"v1": [{"name": "<name>", "type": "DATASET"}]},
                "procedures": {
                    "v1": {"workspaceProcedures": ["<workspace procedures>"]},
                },
            },
        },
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "request": {
                    "displayName": {"displayName": "<display name>"},
                    "symbol": {"symbol": {"icon": "<icon>"}},
                    "settings": {
                        "refNames": {"v1": [{"name": "<name>", "type": "DATASET"}]},
                        "procedures": {
                            "v1": {"workspaceProcedures": ["<workspace procedures>"]},
                        },
                    },
                },
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "workspace": {
    "id": "<id>",
    "rid": "<rid>",
    "org": "<org>",
    "displayName": "<display name>",
    "symbol": {
      "icon": "<icon>"
    },
    "settings": {
      "refNames": {
        "v1": [
          {
            "name": "<name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "v1": {
          "workspaceProcedures": [
            "<workspace procedures>"
          ]
        }
      }
    }
  }
}

Get workspace#

GET /workspaces/v2/workspaces/{workspaceRid}

Gets the workspace with the specified WorkspaceRid.

Path parameters

workspaceRid string required

​

Response

workspace Workspace

​

Fields of Workspace
id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string

​

org string

​

displayName string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol
one of icon, emoji, image

​

icon string

Workspace icon name (e.g. castle)

emoji string

Workspace emoji name (e.g. :castle:)

image string

Workspace image url (e.g. https://example.com/image.png)

settings WorkspaceSettings

​

Fields of WorkspaceSettings
refNames PreferredRefNameConfiguration

​

Fields of PreferredRefNameConfiguration
v1 array of RefNameAndType

​

Fields of RefNameAndType
name string

​

type DataSourceType

​

Values of DataSourceType
DATA_SOURCE_TYPE_UNSPECIFIED

​

DATASET

​

CONNECTION

​

VIDEO

​

SPATIAL

​

procedures ProcedureSettings

​

Fields of ProcedureSettings
v1 ProcedureSettingsV1

​

Fields of ProcedureSettingsV1
workspaceProcedures array of string

A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

Request

curl "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "workspace": {
    "id": "<id>",
    "rid": "<rid>",
    "org": "<org>",
    "displayName": "<display name>",
    "symbol": {
      "icon": "<icon>"
    },
    "settings": {
      "refNames": {
        "v1": [
          {
            "name": "<name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "v1": {
          "workspaceProcedures": [
            "<workspace procedures>"
          ]
        }
      }
    }
  }
}

Get workspace banner#

GET /workspaces/v2/workspaces/{workspaceRid}/banner

Gets the classification banner (e.g. CUI, ITAR) configured for a workspace.

Path parameters

workspaceRid string required

​

Response

bannerConfig BannerConfig

Unset if the workspace has no banner configured, or is unrecognized.

Fields of BannerConfig
one of cui, noItar, secret

​

cui CuiBannerConfig

The workspace may contain Controlled Unclassified Information (CUI).

noItar NoItarBannerConfig

The workspace is not authorized to store ITAR-controlled data.

secret SecretBannerConfig

The workspace may contain SECRET classified data.

Request

curl "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>/banner" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>/banner",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>/banner",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/workspaces/v2/workspaces/<workspace rid>/banner",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "bannerConfig": {
    "cui": {}
  }
}

Errors#

Errors shows how these errors are sent.

Each error’s errorName is NominalWorkspacesV1: followed by its name below.

Status

Name

Notes

400

SecurityErrorForbiddenCrossWorkspaceOperation

Workspaces are hard boundaries in Nominal. Resources from different workspaces cannot be combined.

400

SecurityErrorWorkspaceNotSpecified

A workspace was not specified and could not be inferred.

404

SecurityErrorWorkspaceNotFound

The workspace with the specified rid was not found.

Types#

BannerConfig#

Set exactly one of the fields below.

one of cui, noItar, secret required

​

cui CuiBannerConfig

The workspace may contain Controlled Unclassified Information (CUI).

noItar NoItarBannerConfig

The workspace is not authorized to store ITAR-controlled data.

secret SecretBannerConfig

The workspace may contain SECRET classified data.

CuiBannerConfig#

An empty JSON object, {}.

DataSourceType#

DATA_SOURCE_TYPE_UNSPECIFIED

​

DATASET

​

CONNECTION

​

VIDEO

​

SPATIAL

​

NoItarBannerConfig#

An empty JSON object, {}.

PreferredRefNameConfiguration#

v1 array of RefNameAndType

​

ProcedureSettings#

v1 ProcedureSettingsV1

​

ProcedureSettingsV1#

workspaceProcedures array of string

A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

RefNameAndType#

name string

​

type DataSourceType

​

RemoveType#

The request to remove a field from a workspace.

An empty JSON object, {}.

SecretBannerConfig#

An empty JSON object, {}.

UpdateOrRemoveWorkspaceDisplayName#

The request to update the display name of the workspace. The request will replace the existing display name with the display name specified if it’s provided. Otherwise, the current display name will be removed from the workspace.

Set exactly one of the fields below.

one of displayName, removeType required

​

displayName string

​

removeType RemoveType

​

UpdateOrRemoveWorkspaceSymbol#

The request to update the symbol of the workspace. The request will replace the existing symbol with the symbol specified if it’s provided. Otherwise, the current symbol will be removed from the workspace.

Set exactly one of the fields below.

one of symbol, removeType required

​

symbol WorkspaceSymbol

​

removeType RemoveType

​

UpdateWorkspaceRequest#

displayName UpdateOrRemoveWorkspaceDisplayName

​

symbol UpdateOrRemoveWorkspaceSymbol

​

settings WorkspaceSettings

Excluded fields in the settings update will be ignored.

Workspace#

id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string

​

org string

​

displayName string

​

symbol WorkspaceSymbol

​

settings WorkspaceSettings

​

WorkspaceSettings#

refNames PreferredRefNameConfiguration

​

procedures ProcedureSettings

​

WorkspaceSymbol#

Set exactly one of the fields below.

one of icon, emoji, image required

​

icon string

Workspace icon name (e.g. castle)

emoji string

Workspace emoji name (e.g. :castle:)

image string

Workspace image url (e.g. https://example.com/image.png)

Page design based on Scalar, MIT License.