Marking service#

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

OpenAPI file: nominal.authorization.markings.v1.json

Endpoints#

Create marking#

POST /authorization/markings/v1

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.

Body

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

​

authorizedGroups AuthorizedGroups

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

Fields of AuthorizedGroups
groupRids array of string

​

symbol Symbol

​

Fields of Symbol
one of icon, emoji, image required

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

Response

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

​

authorizedGroups AuthorizedGroups

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

Fields of AuthorizedGroups
groupRids array of string

​

symbol Symbol

Symbol and color to identify markings

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  }
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"icon": "<icon>"},
        "color": {"hexCode": "<hex code>"},
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"icon": "<icon>"},
        "color": {"hexCode": "<hex code>"},
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "id": "<id>",
                "description": "<description>",
                "authorizedGroups": {"groupRids": ["<group rids>"]},
                "symbol": {"icon": "<icon>"},
                "color": {"hexCode": "<hex code>"},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}

Archive markings#

POST /authorization/markings/v1/archive-batch

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.

Body

The body is an array of string.

Response

An empty JSON object, {}.

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "string"
]'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch",
            headers={"Authorization": "Bearer <api key>"},
            json=["string"],
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Get authorized groups by marking#

POST /authorization/markings/v1/authorized-groups-by-marking

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.

Body

markingRids array of string

​

Response

authorizedGroupsByMarking map of string to AuthorizedGroups

​

Fields of AuthorizedGroups
groupRids array of string

​

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingRids": [
    "<marking rids>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking",
            headers={"Authorization": "Bearer <api key>"},
            json={"markingRids": ["<marking rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "authorizedGroupsByMarking": {
    "<key>": {
      "groupRids": [
        "<group rids>"
      ]
    }
  }
}

Batch get markings#

POST /authorization/markings/v1/batch-get

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.

Body

markingRids array of string

​

Response

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

​

authorizedGroups AuthorizedGroups

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

Fields of AuthorizedGroups
groupRids array of string

​

symbol Symbol

Symbol and color to identify markings

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingRids": [
    "<marking rids>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json={"markingRids": ["<marking rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "markings": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "authorizedGroups": {
        "groupRids": [
          "<group rids>"
        ]
      },
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hexCode": "<hex code>"
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ]
}

Batch get marking metadata#

POST /authorization/markings/v1/batch-get-metadata

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.

Body

markingRids array of string

​

Response

markingMetadatas 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 string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingRids": [
    "<marking rids>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata",
            headers={"Authorization": "Bearer <api key>"},
            json={"markingRids": ["<marking rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "markingMetadatas": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hexCode": "<hex code>"
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ]
}

Get marking by ID#

GET /authorization/markings/v1/id/{id}

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.

Path parameters

id string required

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

Response

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

​

authorizedGroups AuthorizedGroups

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

Fields of AuthorizedGroups
groupRids array of string

​

symbol Symbol

Symbol and color to identify markings

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

Request

curl "https://api.gov.nominal.io/api/authorization/markings/v1/id/<id>" \
  -H "Authorization: Bearer <api key>"

import requests

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

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/authorization/markings/v1/id/<id>",
    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/authorization/markings/v1/id/<id>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}

Get markings for resources#

POST /authorization/markings/v1/markings-for-resources

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.

Body

resources array of string

The resources to get the markings for.

Response

resourceToMarkings map of string to ResourceMarkingsList

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

Fields of ResourceMarkingsList
appliedMarkings array of AppliedMarking

​

Fields of AppliedMarking
markingRid string

​

appliedAt string (date-time)

​

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "resources": [
    "<resources>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"resources": ["<resources>"]},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"resources": ["<resources>"]},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources",
            headers={"Authorization": "Bearer <api key>"},
            json={"resources": ["<resources>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "resourceToMarkings": {
    "<key>": {
      "appliedMarkings": [
        {
          "markingRid": "<marking rid>",
          "appliedAt": "2026-01-01T00:00:00Z"
        }
      ]
    }
  }
}

Update markings on resource#

POST /authorization/markings/v1/resource/{resource}/markings

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.

Path parameters

resource string required

​

Body

markingsToApply array of string

​

markingsToRemove array of string

​

Response

An empty JSON object, {}.

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingsToApply": [
    "<markings to apply>"
  ],
  "markingsToRemove": [
    "<markings to remove>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "markingsToApply": ["<markings to apply>"],
        "markingsToRemove": ["<markings to remove>"],
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "markingsToApply": ["<markings to apply>"],
        "markingsToRemove": ["<markings to remove>"],
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "markingsToApply": ["<markings to apply>"],
                "markingsToRemove": ["<markings to remove>"],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Search markings#

POST /authorization/markings/v1/search

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

Body

query SearchMarkingsQuery

​

Fields of SearchMarkingsQuery
one of idExactSubstringSearch, and, or required

​

idExactSubstringSearch string

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

and SearchMarkingsQueryList

​

Fields of SearchMarkingsQueryList
queries array of SearchMarkingsQuery

​

or SearchMarkingsQueryList

​

pageSize integer

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

nextPageToken string

​

Response

markingMetadatas 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 string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

nextPageToken string

​

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/search" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "query": {
    "idExactSubstringSearch": "<id exact substring search>"
  },
  "pageSize": 1,
  "nextPageToken": "<next page token>"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"idExactSubstringSearch": "<id exact substring search>"},
        "pageSize": 1,
        "nextPageToken": "<next page token>",
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"idExactSubstringSearch": "<id exact substring search>"},
        "pageSize": 1,
        "nextPageToken": "<next page token>",
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/search",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "query": {"idExactSubstringSearch": "<id exact substring search>"},
                "pageSize": 1,
                "nextPageToken": "<next page token>",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "markingMetadatas": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hexCode": "<hex code>"
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ],
  "nextPageToken": "<next page token>"
}

Unarchive markings#

POST /authorization/markings/v1/unarchive-batch

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.

Body

The body is an array of string.

Response

An empty JSON object, {}.

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "string"
]'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch",
            headers={"Authorization": "Bearer <api key>"},
            json=["string"],
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Get resources for marking#

POST /authorization/markings/v1/{markingRid}/resources

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.

Path parameters

markingRid string required

​

Body

pageSize integer

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

nextPageToken string

​

Response

resources array of MarkedResource

​

Fields of MarkedResource
resource string

​

appliedAt string (date-time)

​

nextPageToken string

​

Request

curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "pageSize": 1,
  "nextPageToken": "<next page token>"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"pageSize": 1, "nextPageToken": "<next page token>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"pageSize": 1, "nextPageToken": "<next page token>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources",
            headers={"Authorization": "Bearer <api key>"},
            json={"pageSize": 1, "nextPageToken": "<next page token>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

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

Get marking#

GET /authorization/markings/v1/{rid}

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.

Path parameters

rid string required

​

Response

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

​

authorizedGroups AuthorizedGroups

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

Fields of AuthorizedGroups
groupRids array of string

​

symbol Symbol

Symbol and color to identify markings

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

Request

curl "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>" \
  -H "Authorization: Bearer <api key>"

import requests

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

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<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/authorization/markings/v1/<rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}

Update marking#

PUT /authorization/markings/v1/{rid}

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.

Path parameters

rid string required

​

Body

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

​

authorizedGroups AuthorizedGroups

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

Fields of AuthorizedGroups
groupRids array of string

​

symbol UpdateMarkingSymbolWrapper

​

Fields of UpdateMarkingSymbolWrapper
value Symbol

​

Fields of Symbol
one of icon, emoji, image required

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color UpdateMarkingColorWrapper

​

Fields of UpdateMarkingColorWrapper
value Color

​

Fields of Color
hexCode string

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

Response

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

​

authorizedGroups AuthorizedGroups

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

Fields of AuthorizedGroups
groupRids array of string

​

symbol Symbol

Symbol and color to identify markings

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

color Color

​

Fields of Color
hexCode string

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

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

Request

curl -X PUT "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "value": {
      "icon": "<icon>"
    }
  },
  "color": {
    "value": {
      "hexCode": "<hex code>"
    }
  }
}'

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"value": {"icon": "<icon>"}},
        "color": {"value": {"hexCode": "<hex code>"}},
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"value": {"icon": "<icon>"}},
        "color": {"value": {"hexCode": "<hex code>"}},
    },
)
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/authorization/markings/v1/<rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "id": "<id>",
                "description": "<description>",
                "authorizedGroups": {"groupRids": ["<group rids>"]},
                "symbol": {"value": {"icon": "<icon>"}},
                "color": {"value": {"hexCode": "<hex code>"}},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}

Types#

AppliedMarking#

markingRid string

​

appliedAt string (date-time)

​

AuthorizedGroups#

groupRids array of string

​

Color#

hexCode string

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

MarkedResource#

resource string

​

appliedAt 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

​

authorizedGroups AuthorizedGroups

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

symbol Symbol

Symbol and color to identify markings

color Color

​

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived 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

​

createdAt string (date-time)

​

updatedAt string (date-time)

​

isArchived boolean

​

ResourceMarkingsList#

appliedMarkings array of AppliedMarking

​

SearchMarkingsQuery#

Set exactly one of the fields below.

one of idExactSubstringSearch, and, or required

​

idExactSubstringSearch string

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

and SearchMarkingsQueryList

​

or SearchMarkingsQueryList

​

SearchMarkingsQueryList#

queries array of SearchMarkingsQuery

​

Symbol#

Set exactly one of the fields below.

one of icon, emoji, image required

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

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

UpdateMarkingColorWrapper#

value Color

​

UpdateMarkingSymbolWrapper#

value Symbol

​

Page design based on Scalar, MIT License.