Marking service (gRPC)#

This service manages Markings, which are a mechanism to restrict access to data sources.

Endpoints#

Archive markings#

gRPC /nominal.authorization.markings.v1.MarkingService/ArchiveMarkings

Archives markings. Archiving a marking is an idempotent operation that prevents further changes or applications of the marking. Archived markings will not appear in search but can be retrieved by get endpoints. Throws HTTP 403 / gRPC 7 if the user does not have permission to archive one or more of the markings or if any of the markings are not found. Throws HTTP 400 / gRPC 3 if the archived marking is currently applied to one or more resources.

Request: ArchiveMarkingsRequest

marking_rids array of string

Response: ArchiveMarkingsResponse

A message with no fields.

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.ArchiveMarkingsRequest(marking_rids=["<marking rids>"])
response = marking_service.ArchiveMarkings(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.ArchiveMarkingsRequest{
		MarkingRids: []string{
			"<marking rids>",
		},
	}
	response, err := markingService.ArchiveMarkings(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{}

Batch get marking metadata#

gRPC /nominal.authorization.markings.v1.MarkingService/BatchGetMarkingMetadata

Gets metadata for multiple markings by RID. Metadata does not include the authorized groups. If a marking is not found or the user doesn’t have permission to read it, it will not be included in the response.

Request: BatchGetMarkingMetadataRequest

marking_rids array of string

Response: BatchGetMarkingMetadataResponse

marking_metadatas array of MarkingMetadata

Fields of MarkingMetadata

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

symbol Symbol

Symbol and color to identify markings

Fields of Symbol

one of icon, emoji, image

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

created_at string (date-time)

updated_at string (date-time)

is_archived boolean

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.BatchGetMarkingMetadataRequest(marking_rids=["<marking rids>"])
response = marking_service.BatchGetMarkingMetadata(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.BatchGetMarkingMetadataRequest{
		MarkingRids: []string{
			"<marking rids>",
		},
	}
	response, err := markingService.BatchGetMarkingMetadata(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "marking_metadatas": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hex_code": "<hex code>"
      },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "is_archived": true
    }
  ]
}

Batch get markings#

gRPC /nominal.authorization.markings.v1.MarkingService/BatchGetMarkings

Gets multiple markings by RID. If a marking is not found or the user doesn’t have permission to read it, it will not be included in the response.

Request: BatchGetMarkingsRequest

marking_rids array of string

Response: BatchGetMarkingsResponse

markings array of Marking

Fields of Marking

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

authorized_groups AuthorizedGroups

Group RIDs that are authorized to access data sources with this marking.

Fields of AuthorizedGroups

group_rids array of string

symbol Symbol

Symbol and color to identify markings

Fields of Symbol

one of icon, emoji, image

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

created_at string (date-time)

updated_at string (date-time)

is_archived boolean

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.BatchGetMarkingsRequest(marking_rids=["<marking rids>"])
response = marking_service.BatchGetMarkings(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.BatchGetMarkingsRequest{
		MarkingRids: []string{
			"<marking rids>",
		},
	}
	response, err := markingService.BatchGetMarkings(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "markings": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "authorized_groups": {
        "group_rids": [
          "<group rids>"
        ]
      },
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hex_code": "<hex code>"
      },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "is_archived": true
    }
  ]
}

Create marking#

gRPC /nominal.authorization.markings.v1.MarkingService/CreateMarking

Creates a marking. Throws HTTP 409 / gRPC 6 if a marking with the same ID already exists. Throws HTTP 403 / gRPC 7 if the user does not have permission to create a marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to read some of the specified groups.

Request: CreateMarkingRequest

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

authorized_groups AuthorizedGroups

Group RIDs that are authorized to access data sources with this marking.

Fields of AuthorizedGroups

group_rids array of string

symbol Symbol

Fields of Symbol

one of icon, emoji, image required

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

Response: CreateMarkingResponse

marking Marking

Fields of Marking

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

authorized_groups AuthorizedGroups

Group RIDs that are authorized to access data sources with this marking.

Fields of AuthorizedGroups

group_rids array of string

symbol Symbol

Symbol and color to identify markings

Fields of Symbol

one of icon, emoji, image

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

created_at string (date-time)

updated_at string (date-time)

is_archived boolean

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.CreateMarkingRequest(
    id="<id>",
    description="<description>",
    authorized_groups={"group_rids": ["<group rids>"]},
    symbol={"icon": "<icon>"},
    color={"hex_code": "<hex code>"},
)
response = marking_service.CreateMarking(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/v1"
	elementsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/scout/elements/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.CreateMarkingRequest{
		Id:          "<id>",
		Description: "<description>",
		AuthorizedGroups: &markingsv1.AuthorizedGroups{
			GroupRids: []string{
				"<group rids>",
			},
		},
		Symbol: &elementsv1.Symbol{
			Symbol: &elementsv1.Symbol_Icon{Icon: "<icon>"},
		},
		Color: &elementsv1.Color{
			Color: &elementsv1.Color_HexCode{HexCode: "<hex code>"},
		},
	}
	response, err := markingService.CreateMarking(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "marking": {
    "rid": "<rid>",
    "id": "<id>",
    "description": "<description>",
    "authorized_groups": {
      "group_rids": [
        "<group rids>"
      ]
    },
    "symbol": {
      "icon": "<icon>"
    },
    "color": {
      "hex_code": "<hex code>"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "is_archived": true
  }
}

Get authorized groups by marking#

gRPC /nominal.authorization.markings.v1.MarkingService/GetAuthorizedGroupsByMarking

Gets the authorized Groups for each of a set of Markings. Markings that are not found or for which the user does not have permission to read will be filtered from the response. Groups for which the user does not have permission to read will be filtered from the response.

Request: GetAuthorizedGroupsByMarkingRequest

marking_rids array of string

Response: GetAuthorizedGroupsByMarkingResponse

authorized_groups_by_marking map of string to AuthorizedGroups

Fields of AuthorizedGroups

group_rids array of string

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.GetAuthorizedGroupsByMarkingRequest(
    marking_rids=["<marking rids>"],
)
response = marking_service.GetAuthorizedGroupsByMarking(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.GetAuthorizedGroupsByMarkingRequest{
		MarkingRids: []string{
			"<marking rids>",
		},
	}
	response, err := markingService.GetAuthorizedGroupsByMarking(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "authorized_groups_by_marking": {
    "<key>": {
      "group_rids": [
        "<group rids>"
      ]
    }
  }
}

Get marking#

gRPC /nominal.authorization.markings.v1.MarkingService/GetMarking

Gets a marking by its RID. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking. Throws HTTP 403 / gRPC 5 if the marking is not found.

Request: GetMarkingRequest

rid string

Response: GetMarkingResponse

marking Marking

Fields of Marking

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

authorized_groups AuthorizedGroups

Group RIDs that are authorized to access data sources with this marking.

Fields of AuthorizedGroups

group_rids array of string

symbol Symbol

Symbol and color to identify markings

Fields of Symbol

one of icon, emoji, image

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

created_at string (date-time)

updated_at string (date-time)

is_archived boolean

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.GetMarkingRequest(rid="<rid>")
response = marking_service.GetMarking(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.GetMarkingRequest{
		Rid: "<rid>",
	}
	response, err := markingService.GetMarking(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "marking": {
    "rid": "<rid>",
    "id": "<id>",
    "description": "<description>",
    "authorized_groups": {
      "group_rids": [
        "<group rids>"
      ]
    },
    "symbol": {
      "icon": "<icon>"
    },
    "color": {
      "hex_code": "<hex code>"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "is_archived": true
  }
}

Get marking by ID#

gRPC /nominal.authorization.markings.v1.MarkingService/GetMarkingById

Gets a marking by its ID, a human-readable identifier unique within the org. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking. Throws HTTP 403 / gRPC 5 if the marking is not found.

Request: GetMarkingByIdRequest

id string: Matches ^[a-z][a-z0-9-]*$.

Response: GetMarkingByIdResponse

marking Marking

Fields of Marking

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

authorized_groups AuthorizedGroups

Group RIDs that are authorized to access data sources with this marking.

Fields of AuthorizedGroups

group_rids array of string

symbol Symbol

Symbol and color to identify markings

Fields of Symbol

one of icon, emoji, image

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

created_at string (date-time)

updated_at string (date-time)

is_archived boolean

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.GetMarkingByIdRequest(id="<id>")
response = marking_service.GetMarkingById(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.GetMarkingByIdRequest{
		Id: "<id>",
	}
	response, err := markingService.GetMarkingById(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "marking": {
    "rid": "<rid>",
    "id": "<id>",
    "description": "<description>",
    "authorized_groups": {
      "group_rids": [
        "<group rids>"
      ]
    },
    "symbol": {
      "icon": "<icon>"
    },
    "color": {
      "hex_code": "<hex code>"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "is_archived": true
  }
}

Get markings for resources#

gRPC /nominal.authorization.markings.v1.MarkingService/GetMarkingsForResources

Gets the requested resources and the markings applied to them. Since the number of markings applied to a resource is typically small, this endpoint will return all markings for each resource. Any unauthorized resources or markings will be filtered from the response.

Request: GetMarkingsForResourcesRequest

resources array of string: The resources to get the markings for.

Response: GetMarkingsForResourcesResponse

resource_to_markings map of string to ResourceMarkingsList

A map from resource ID to the markings applied to them.

Fields of ResourceMarkingsList

applied_markings array of AppliedMarking

Fields of AppliedMarking

marking_rid string
applied_at string (date-time)

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.GetMarkingsForResourcesRequest(resources=["<resources>"])
response = marking_service.GetMarkingsForResources(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.GetMarkingsForResourcesRequest{
		Resources: []string{
			"<resources>",
		},
	}
	response, err := markingService.GetMarkingsForResources(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "resource_to_markings": {
    "<key>": {
      "applied_markings": [
        {
          "marking_rid": "<marking rid>",
          "applied_at": "2026-01-01T00:00:00Z"
        }
      ]
    }
  }
}

Get resources for marking#

gRPC /nominal.authorization.markings.v1.MarkingService/GetResourcesForMarking

Gets the resources that a Marking is applied to. This endpoint is paginated. Any unauthorized resources will be filtered from the response. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking.

Request: GetResourcesForMarkingRequest

marking_rid string
page_size integer: Page sizes greater than 1_000 will be rejected. Default pageSize is 100. From 1 to 1,000.
next_page_token string

Response: GetResourcesForMarkingResponse

resources array of MarkedResource

Fields of MarkedResource

resource string
applied_at string (date-time)

next_page_token string

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.GetResourcesForMarkingRequest(
    marking_rid="<marking rid>",
    page_size=1,
    next_page_token="<next page token>",
)
response = marking_service.GetResourcesForMarking(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
)

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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.GetResourcesForMarkingRequest{
		MarkingRid:    "<marking rid>",
		PageSize:      proto.Int32(1),
		NextPageToken: proto.String("<next page token>"),
	}
	response, err := markingService.GetResourcesForMarking(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "resources": [
    {
      "resource": "<resource>",
      "applied_at": "2026-01-01T00:00:00Z"
    }
  ],
  "next_page_token": "<next page token>"
}

Search markings#

gRPC /nominal.authorization.markings.v1.MarkingService/SearchMarkings

Search Markings, returning paged results. Throws HTTP 400 / gRPC 3 if the query is incorrectly formed.

Request: SearchMarkingsRequest

query SearchMarkingsQuery

Fields of SearchMarkingsQuery

one of id_exact_substring_search, and, or required

id_exact_substring_search

id_exact_substring_search string: Search for markings with an ID that contains the given query as a substring.

and

and SearchMarkingsQueryList

Fields of SearchMarkingsQueryList

queries array of SearchMarkingsQuery

or SearchMarkingsQueryList

page_size integer

Page sizes greater than 1_000 will be rejected. Default pageSize is 100. From 1 to 1,000.

next_page_token string

Response: SearchMarkingsResponse

marking_metadatas array of MarkingMetadata

Fields of MarkingMetadata

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

symbol Symbol

Symbol and color to identify markings

Fields of Symbol

one of icon, emoji, image

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

created_at string (date-time)

updated_at string (date-time)

is_archived boolean

next_page_token string

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.SearchMarkingsRequest(
    query={"id_exact_substring_search": "<id exact substring search>"},
    page_size=1,
    next_page_token="<next page token>",
)
response = marking_service.SearchMarkings(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
)

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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.SearchMarkingsRequest{
		Query: &markingsv1.SearchMarkingsQuery{
			Query: &markingsv1.SearchMarkingsQuery_IdExactSubstringSearch{IdExactSubstringSearch: "<id exact substring search>"},
		},
		PageSize:      proto.Int32(1),
		NextPageToken: proto.String("<next page token>"),
	}
	response, err := markingService.SearchMarkings(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "marking_metadatas": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hex_code": "<hex code>"
      },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "is_archived": true
    }
  ],
  "next_page_token": "<next page token>"
}

Unarchive markings#

gRPC /nominal.authorization.markings.v1.MarkingService/UnarchiveMarkings

Unarchives markings. Restores ability to apply and modify marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to unarchive one or more of the markings or if any of the markings are not found.

Request: UnarchiveMarkingsRequest

marking_rids array of string

Response: UnarchiveMarkingsResponse

A message with no fields.

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.UnarchiveMarkingsRequest(marking_rids=["<marking rids>"])
response = marking_service.UnarchiveMarkings(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.UnarchiveMarkingsRequest{
		MarkingRids: []string{
			"<marking rids>",
		},
	}
	response, err := markingService.UnarchiveMarkings(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{}

Update marking#

gRPC /nominal.authorization.markings.v1.MarkingService/UpdateMarking

Updates a marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to update the marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to read any of the specified groups. Throws HTTP 403 / gRPC 5 if the marking is not found. Throws HTTP 409 / gRPC 6 if trying to update the ID of a marking to an ID that already exists. Throws HTTP 400 / gRPC 3 if trying to update an archived marking.

Request: UpdateMarkingRequest

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

authorized_groups AuthorizedGroups

Group RIDs that are authorized to access data sources with this marking.

Fields of AuthorizedGroups

group_rids array of string

symbol UpdateMarkingSymbolWrapper

Fields of UpdateMarkingSymbolWrapper

value Symbol

Fields of Symbol

one of icon, emoji, image required

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color UpdateMarkingColorWrapper

Fields of UpdateMarkingColorWrapper

value Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

Response: UpdateMarkingResponse

marking Marking

Fields of Marking

rid string

id string

Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.

description string

authorized_groups AuthorizedGroups

Group RIDs that are authorized to access data sources with this marking.

Fields of AuthorizedGroups

group_rids array of string

symbol Symbol

Symbol and color to identify markings

Fields of Symbol

one of icon, emoji, image

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

color Color

Fields of Color

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

created_at string (date-time)

updated_at string (date-time)

is_archived boolean

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.UpdateMarkingRequest(
    rid="<rid>",
    id="<id>",
    description="<description>",
    authorized_groups={"group_rids": ["<group rids>"]},
    symbol={"value": {"icon": "<icon>"}},
    color={"value": {"hex_code": "<hex code>"}},
)
response = marking_service.UpdateMarking(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/v1"
	elementsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/scout/elements/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
)

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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.UpdateMarkingRequest{
		Rid:         "<rid>",
		Id:          proto.String("<id>"),
		Description: proto.String("<description>"),
		AuthorizedGroups: &markingsv1.AuthorizedGroups{
			GroupRids: []string{
				"<group rids>",
			},
		},
		Symbol: &markingsv1.UpdateMarkingRequest_UpdateMarkingSymbolWrapper{
			Value: &elementsv1.Symbol{
				Symbol: &elementsv1.Symbol_Icon{Icon: "<icon>"},
			},
		},
		Color: &markingsv1.UpdateMarkingRequest_UpdateMarkingColorWrapper{
			Value: &elementsv1.Color{
				Color: &elementsv1.Color_HexCode{HexCode: "<hex code>"},
			},
		},
	}
	response, err := markingService.UpdateMarking(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "marking": {
    "rid": "<rid>",
    "id": "<id>",
    "description": "<description>",
    "authorized_groups": {
      "group_rids": [
        "<group rids>"
      ]
    },
    "symbol": {
      "icon": "<icon>"
    },
    "color": {
      "hex_code": "<hex code>"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "is_archived": true
  }
}

Update markings on resource#

gRPC /nominal.authorization.markings.v1.MarkingService/UpdateMarkingsOnResource

Update the markings that are applied on a resource. Supports applying and removing markings at once. This endpoint can be used to atomically replace the markings on a resource, or bulk apply/remove markings. This operation is idempotent and will not throw an error if the marking is already applied/removed on the resource. If a resource marking pair is present in both markings_to_apply and markings_to_remove, this will throw. Throws HTTP 403 / gRPC 7 if the user does not have permission to change the markings on the resource. Throws HTTP 400 / gRPC 3 if trying to apply an archived marking.

Request: UpdateMarkingsOnResourceRequest

resource string
markings_to_apply array of string
markings_to_remove array of string

Response: UpdateMarkingsOnResourceResponse

A message with no fields.

Request

Python

import grpc
from nominal.protos.authorization.markings.v1 import markings_pb2, markings_pb2_grpc

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

request = markings_pb2.UpdateMarkingsOnResourceRequest(
    resource="<resource>",
    markings_to_apply=["<markings to apply>"],
    markings_to_remove=["<markings to remove>"],
)
response = marking_service.UpdateMarkingsOnResource(request, metadata=auth)
print(response)

package main

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

	markingsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/markings/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()
	markingService := markingsv1.NewMarkingServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &markingsv1.UpdateMarkingsOnResourceRequest{
		Resource: "<resource>",
		MarkingsToApply: []string{
			"<markings to apply>",
		},
		MarkingsToRemove: []string{
			"<markings to remove>",
		},
	}
	response, err := markingService.UpdateMarkingsOnResource(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{}

Types#

AppliedMarking#

marking_rid string
applied_at string (date-time)

AuthorizedGroups#

group_rids array of string

Color#

hex_code string: hex color Matches ^#[0-9a-f]{6}$.

MarkedResource#

resource string
applied_at string (date-time)

Marking#

rid string
id string: Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.
description string
authorized_groups AuthorizedGroups: Group RIDs that are authorized to access data sources with this marking.
symbol Symbol: Symbol and color to identify markings
color Color
created_at string (date-time)
updated_at string (date-time)
is_archived boolean

MarkingMetadata#

A leaner representation of a Marking that doesn’t include the authorized groups.

rid string
id string: Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches ^[a-z][a-z0-9-]*$.
description string
symbol Symbol: Symbol and color to identify markings
color Color
created_at string (date-time)
updated_at string (date-time)
is_archived boolean

ResourceMarkingsList#

applied_markings array of AppliedMarking

SearchMarkingsQuery#

Set exactly one of the fields below.

one of id_exact_substring_search, and, or required

id_exact_substring_search

id_exact_substring_search string: Search for markings with an ID that contains the given query as a substring.

and

and SearchMarkingsQueryList

or SearchMarkingsQueryList

SearchMarkingsQueryList#

queries array of SearchMarkingsQuery

Symbol#

Set exactly one of the fields below.

one of icon, emoji, image required

icon

icon string: Icon name (e.g. castle)

emoji

emoji string: Emoji name (e.g. :castle:)

image

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

UpdateMarkingColorWrapper#

value Color

UpdateMarkingSymbolWrapper#

value Symbol

Page design based on Scalar, MIT License.