Workspace service (gRPC)

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

Endpoints

Get default workspace

gRPC /nominal.workspaces.v1.WorkspaceService/GetDefaultWorkspace

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: GetDefaultWorkspaceRequest

A message with no fields.

Response: GetDefaultWorkspaceResponse

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

​

display_name string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol

one of icon, emoji, image

​

icon

icon string

Workspace icon name (e.g. castle)

emoji

emoji string

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

image

image string

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

settings WorkspaceSettings

​

Fields of WorkspaceSettings

ref_names 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

workspace_procedures 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

Python

import grpc
from nominal.protos.workspaces.v1 import workspaces_pb2, workspaces_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
workspace_service = workspaces_pb2_grpc.WorkspaceServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = workspaces_pb2.GetDefaultWorkspaceRequest()
response = workspace_service.GetDefaultWorkspace(request, metadata=auth)
print(response)

Go

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	workspacesv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/workspaces/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	workspaceService := workspacesv1.NewWorkspaceServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &workspacesv1.GetDefaultWorkspaceRequest{}
	response, err := workspaceService.GetDefaultWorkspace(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "workspace": {
    "id": "<id>",
    "rid": "<rid>",
    "org": "<org>",
    "display_name": "<display name>",
    "symbol": {
      "icon": "<icon>"
    },
    "settings": {
      "ref_names": {
        "v1": [
          {
            "name": "<name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "v1": {
          "workspace_procedures": [
            "<workspace procedures>"
          ]
        }
      }
    }
  }
}

Get workspace

gRPC /nominal.workspaces.v1.WorkspaceService/GetWorkspace

Gets the workspace with the specified WorkspaceRid.

Request: GetWorkspaceRequest

workspace_rid string

​

Response: GetWorkspaceResponse

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

​

display_name string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol

one of icon, emoji, image

​

icon

icon string

Workspace icon name (e.g. castle)

emoji

emoji string

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

image

image string

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

settings WorkspaceSettings

​

Fields of WorkspaceSettings

ref_names 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

workspace_procedures 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

Python

import grpc
from nominal.protos.workspaces.v1 import workspaces_pb2, workspaces_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
workspace_service = workspaces_pb2_grpc.WorkspaceServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = workspaces_pb2.GetWorkspaceRequest(workspace_rid="<workspace rid>")
response = workspace_service.GetWorkspace(request, metadata=auth)
print(response)

Go

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	workspacesv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/workspaces/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	workspaceService := workspacesv1.NewWorkspaceServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &workspacesv1.GetWorkspaceRequest{
		WorkspaceRid: "<workspace rid>",
	}
	response, err := workspaceService.GetWorkspace(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "workspace": {
    "id": "<id>",
    "rid": "<rid>",
    "org": "<org>",
    "display_name": "<display name>",
    "symbol": {
      "icon": "<icon>"
    },
    "settings": {
      "ref_names": {
        "v1": [
          {
            "name": "<name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "v1": {
          "workspace_procedures": [
            "<workspace procedures>"
          ]
        }
      }
    }
  }
}

Get workspace banner

gRPC /nominal.workspaces.v1.WorkspaceService/GetWorkspaceBanner

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

Request: GetWorkspaceBannerRequest

workspace_rid string

​

Response: GetWorkspaceBannerResponse

banner_config BannerConfig

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

Fields of BannerConfig

one of cui, no_itar, secret

​

cui

cui CuiBannerConfig

The workspace may contain Controlled Unclassified Information (CUI).

no_itar

no_itar NoItarBannerConfig

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

secret

secret SecretBannerConfig

The workspace may contain SECRET classified data.

Request

Python

import grpc
from nominal.protos.workspaces.v1 import workspaces_pb2, workspaces_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
workspace_service = workspaces_pb2_grpc.WorkspaceServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = workspaces_pb2.GetWorkspaceBannerRequest(workspace_rid="<workspace rid>")
response = workspace_service.GetWorkspaceBanner(request, metadata=auth)
print(response)

Go

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	workspacesv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/workspaces/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	workspaceService := workspacesv1.NewWorkspaceServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &workspacesv1.GetWorkspaceBannerRequest{
		WorkspaceRid: "<workspace rid>",
	}
	response, err := workspaceService.GetWorkspaceBanner(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "banner_config": {
    "cui": {}
  }
}

Get workspaces

gRPC /nominal.workspaces.v1.WorkspaceService/GetWorkspaces

Gets all workspaces that the requesting user belongs to.

Request: GetWorkspacesRequest

filter_by_session_org boolean

When unset, defaults to true.

include_guest_workspaces boolean

When unset, defaults to false.

include_role_bound_workspaces boolean

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

Response: GetWorkspacesResponse

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

​

display_name string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol

one of icon, emoji, image

​

icon

icon string

Workspace icon name (e.g. castle)

emoji

emoji string

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

image

image string

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

settings WorkspaceSettings

​

Fields of WorkspaceSettings

ref_names 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

workspace_procedures 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

Python

import grpc
from nominal.protos.workspaces.v1 import workspaces_pb2, workspaces_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
workspace_service = workspaces_pb2_grpc.WorkspaceServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = workspaces_pb2.GetWorkspacesRequest(
    filter_by_session_org=True,
    include_guest_workspaces=True,
    include_role_bound_workspaces=True,
)
response = workspace_service.GetWorkspaces(request, metadata=auth)
print(response)

Response

{
  "workspaces": [
    {
      "id": "<id>",
      "rid": "<rid>",
      "org": "<org>",
      "display_name": "<display name>",
      "symbol": {
        "icon": "<icon>"
      },
      "settings": {
        "ref_names": {
          "v1": [
            {
              "name": "<name>",
              "type": "DATASET"
            }
          ]
        },
        "procedures": {
          "v1": {
            "workspace_procedures": [
              "<workspace procedures>"
            ]
          }
        }
      }
    }
  ]
}

Update workspace

gRPC /nominal.workspaces.v1.WorkspaceService/UpdateWorkspace

Updates the settings of the workspace with the specified WorkspaceRid.

Request: UpdateWorkspaceRequestWrapper

rid string

​

request UpdateWorkspaceRequest

​

Fields of UpdateWorkspaceRequest

display_name UpdateOrRemoveWorkspaceDisplayName

​

Fields of UpdateOrRemoveWorkspaceDisplayName

one of display_name, remove_type required

​

display_name

display_name string

​

remove_type

remove_type RemoveType

​

symbol UpdateOrRemoveWorkspaceSymbol

​

Fields of UpdateOrRemoveWorkspaceSymbol

one of symbol, remove_type required

​

symbol

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol

one of icon, emoji, image required

​

icon

icon string

Workspace icon name (e.g. castle)

emoji

emoji string

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

image

image string

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

remove_type

remove_type RemoveType

​

settings WorkspaceSettings

Excluded fields in the settings update will be ignored.

Fields of WorkspaceSettings

ref_names 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

workspace_procedures 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: UpdateWorkspaceResponse

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

​

display_name string

​

symbol WorkspaceSymbol

​

Fields of WorkspaceSymbol

one of icon, emoji, image

​

icon

icon string

Workspace icon name (e.g. castle)

emoji

emoji string

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

image

image string

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

settings WorkspaceSettings

​

Fields of WorkspaceSettings

ref_names 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

workspace_procedures 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

Python

import grpc
from nominal.protos.workspaces.v1 import workspaces_pb2, workspaces_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
workspace_service = workspaces_pb2_grpc.WorkspaceServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = workspaces_pb2.UpdateWorkspaceRequestWrapper(
    rid="<rid>",
    request={
        "display_name": {"display_name": "<display name>"},
        "symbol": {"symbol": {"icon": "<icon>"}},
        "settings": {
            "ref_names": {"v1": [{"name": "<name>", "type": "DATASET"}]},
            "procedures": {"v1": {"workspace_procedures": ["<workspace procedures>"]}},
        },
    },
)
response = workspace_service.UpdateWorkspace(request, metadata=auth)
print(response)

Go

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	"github.com/nominal-io/nominal-api-protos-go/nominal/protos/types"
	workspacesv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/workspaces/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	workspaceService := workspacesv1.NewWorkspaceServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &workspacesv1.UpdateWorkspaceRequestWrapper{
		Rid: "<rid>",
		Request: &workspacesv1.UpdateWorkspaceRequest{
			DisplayName: &workspacesv1.UpdateOrRemoveWorkspaceDisplayName{
				UpdateOrRemoveWorkspaceDisplayName: &workspacesv1.UpdateOrRemoveWorkspaceDisplayName_DisplayName{DisplayName: "<display name>"},
			},
			Symbol: &workspacesv1.UpdateOrRemoveWorkspaceSymbol{
				UpdateOrRemoveWorkspaceSymbol: &workspacesv1.UpdateOrRemoveWorkspaceSymbol_Symbol{Symbol: &workspacesv1.WorkspaceSymbol{
					WorkspaceSymbol: &workspacesv1.WorkspaceSymbol_Icon{Icon: "<icon>"},
				}},
			},
			Settings: &workspacesv1.WorkspaceSettings{
				RefNames: &workspacesv1.PreferredRefNameConfiguration{
					V1: []*types.RefNameAndType{
						{
							Name: "<name>",
							Type: types.DataSourceType_DATASET,
						},
					},
				},
				Procedures: &workspacesv1.ProcedureSettings{
					ProcedureSettings: &workspacesv1.ProcedureSettings_V1{V1: &workspacesv1.ProcedureSettingsV1{
						WorkspaceProcedures: []string{
							"<workspace procedures>",
						},
					}},
				},
			},
		},
	}
	response, err := workspaceService.UpdateWorkspace(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "workspace": {
    "id": "<id>",
    "rid": "<rid>",
    "org": "<org>",
    "display_name": "<display name>",
    "symbol": {
      "icon": "<icon>"
    },
    "settings": {
      "ref_names": {
        "v1": [
          {
            "name": "<name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "v1": {
          "workspace_procedures": [
            "<workspace procedures>"
          ]
        }
      }
    }
  }
}

Errors

Errors shows how these errors are sent.

Code	Reason	Message
INVALID_ARGUMENT	SECURITY_ERROR_FORBIDDEN_CROSS_WORKSPACE_OPERATION	Workspaces are hard boundaries in Nominal. Resources from different workspaces cannot be combined.
INVALID_ARGUMENT	SECURITY_ERROR_WORKSPACE_NOT_SPECIFIED	A workspace was not specified and could not be inferred.
NOT_FOUND	SECURITY_ERROR_WORKSPACE_NOT_FOUND	The workspace with the specified rid was not found.

Types

BannerConfig

Set exactly one of the fields below.

one of cui, no_itar, secret required

​

cui

cui CuiBannerConfig

The workspace may contain Controlled Unclassified Information (CUI).

no_itar

no_itar NoItarBannerConfig

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

secret

secret SecretBannerConfig

The workspace may contain SECRET classified data.

CuiBannerConfig

A message with no fields.

DataSourceType

DATA_SOURCE_TYPE_UNSPECIFIED

​

DATASET

​

CONNECTION

​

VIDEO

​

SPATIAL

​

NoItarBannerConfig

A message with no fields.

PreferredRefNameConfiguration

v1 array of RefNameAndType

​

ProcedureSettings

v1 ProcedureSettingsV1

​

ProcedureSettingsV1

workspace_procedures 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.

A message with no fields.

SecretBannerConfig

A message with no fields.

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 display_name, remove_type required

​

display_name

display_name string

​

remove_type

remove_type 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, remove_type required

​

symbol

symbol WorkspaceSymbol

​

remove_type

remove_type RemoveType

​

UpdateWorkspaceRequest

display_name 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

​

display_name string

​

symbol WorkspaceSymbol

​

settings WorkspaceSettings

​

WorkspaceSettings

ref_names PreferredRefNameConfiguration

​

procedures ProcedureSettings

​

WorkspaceSymbol

Set exactly one of the fields below.

one of icon, emoji, image required

​

icon

icon string

Workspace icon name (e.g. castle)

emoji

emoji string

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

image

image string

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

Page design based on Scalar, MIT License.