Secrets service

The secrets service provides functionality for creating and retrieving customer secrets (e.g. influx passwords, API keys, etc)

OpenAPI file: SecretService.json

Endpoints

Create

POST /secrets/v1/secrets

Create a new secret.

Body

name string required

​

description string required

​

decryptedValue string required

​

properties map of PropertyName to string

​

labels array of string

​

workspace string (RID)

The workspace in which to create the secret. If not provided, the secret will be created in the default workspace for the user’s organization, if the default workspace for the organization is configured.

Response

rid string (RID)

​

name string

​

description string

​

createdBy string (RID)

​

properties map of PropertyName to string

​

labels array of string

​

createdAt string (date-time)

​

isArchived boolean

​

Request

curl

curl -X POST "https://api.gov.nominal.io/api/secrets/v1/secrets" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "<name>",
  "description": "<description>",
  "decryptedValue": "<decrypted value>"
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/secrets/v1/secrets",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "description": "<description>",
        "decryptedValue": "<decrypted value>",
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/secrets/v1/secrets",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "description": "<description>",
        "decryptedValue": "<decrypted value>",
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/secrets/v1/secrets",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "name": "<name>",
                "description": "<description>",
                "decryptedValue": "<decrypted value>",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "rid": "<secret rid>",
  "name": "<name>",
  "description": "<description>",
  "createdBy": "<created by>",
  "properties": {
    "<key>": "<property value>"
  },
  "labels": [
    "<label>"
  ],
  "createdAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}

Get

GET /secrets/v1/secrets/{rid}

Get secret by rid.

Path parameters

rid string (RID) required

​

Response

rid string (RID)

​

name string

​

description string

​

createdBy string (RID)

​

properties map of PropertyName to string

​

labels array of string

​

createdAt string (date-time)

​

isArchived boolean

​

Request

curl

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

requests

import requests

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

httpx

import httpx

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

aiohttp

import asyncio

import aiohttp


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


asyncio.run(main())

Response: 200

{
  "rid": "<secret rid>",
  "name": "<name>",
  "description": "<description>",
  "createdBy": "<created by>",
  "properties": {
    "<key>": "<property value>"
  },
  "labels": [
    "<label>"
  ],
  "createdAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}

Update

PUT /secrets/v1/secrets/{rid}

Update a secret by rid.

Path parameters

rid string (RID) required

​

Body

name string

​

description string

​

properties map of PropertyName to string

​

labels array of string

​

decryptedValue string

​

Response

rid string (RID)

​

name string

​

description string

​

createdBy string (RID)

​

properties map of PropertyName to string

​

labels array of string

​

createdAt string (date-time)

​

isArchived boolean

​

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "<name>",
  "description": "<description>",
  "properties": {
    "<key>": "<property value>"
  },
  "labels": [
    "<label>"
  ],
  "decryptedValue": "<decrypted value>"
}'

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "description": "<description>",
        "properties": {"<key>": "<property value>"},
        "labels": ["<label>"],
        "decryptedValue": "<decrypted value>",
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "description": "<description>",
        "properties": {"<key>": "<property value>"},
        "labels": ["<label>"],
        "decryptedValue": "<decrypted value>",
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "name": "<name>",
                "description": "<description>",
                "properties": {"<key>": "<property value>"},
                "labels": ["<label>"],
                "decryptedValue": "<decrypted value>",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "rid": "<secret rid>",
  "name": "<name>",
  "description": "<description>",
  "createdBy": "<created by>",
  "properties": {
    "<key>": "<property value>"
  },
  "labels": [
    "<label>"
  ],
  "createdAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}

Delete

DELETE /secrets/v1/secrets/{rid}

Delete a secret by rid. This is a permanent deletion. To perform a soft delete, use the archive endpoint.

Path parameters

rid string (RID) required

​

Response

No content (HTTP 204).

Request

curl

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

requests

import requests

response = requests.delete(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.delete(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.delete(
            "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Get batch

POST /secrets/v1/secrets/batch

Get secrets by a set of rids.

Body

secretRids array of string (RID)

​

Response

response array of Secret

​

Fields of Secret

rid string (RID)

​

name string

​

description string

​

createdBy string (RID)

​

properties map of PropertyName to string

​

labels array of string

​

createdAt string (date-time)

​

isArchived boolean

​

Request

curl

curl -X POST "https://api.gov.nominal.io/api/secrets/v1/secrets/batch" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "secretRids": [
    "<secret rid>"
  ]
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/batch",
    headers={"Authorization": "Bearer <api key>"},
    json={"secretRids": ["<secret rid>"]},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/batch",
    headers={"Authorization": "Bearer <api key>"},
    json={"secretRids": ["<secret rid>"]},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


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


asyncio.run(main())

Response: 200

{
  "response": [
    {
      "rid": "<secret rid>",
      "name": "<name>",
      "description": "<description>",
      "createdBy": "<created by>",
      "properties": {
        "<key>": "<property value>"
      },
      "labels": [
        "<label>"
      ],
      "createdAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ]
}

Archive

PUT /secrets/v1/secrets/{rid}/archive

Archive a secret by rid.

Path parameters

rid string (RID) required

​

Response

No content (HTTP 204).

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/archive" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/archive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/archive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/archive",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Unarchive

PUT /secrets/v1/secrets/{rid}/unarchive

Unarchive a secret by rid.

Path parameters

rid string (RID) required

​

Response

No content (HTTP 204).

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/unarchive" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/unarchive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/unarchive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/secrets/v1/secrets/<rid>/unarchive",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Search

POST /secrets/v1/secrets/search

Returns metadata about secrets that match a given query.

Body

query SearchSecretsQuery required

​

searchText

Set type to "searchText".

searchText string

​

label

Set type to "label".

label string

​

property

Set type to "property".

property Property

​

Fields of Property

name string required

​

value string required

​

and

Set type to "and".

and array of SearchSecretsQuery

​

or

Set type to "or".

or array of SearchSecretsQuery

​

workspace

Set type to "workspace".

workspace string (RID)

​

pageSize integer

Defaults to 100. Will throw if larger than 1000.

sort SortOptions required

​

Fields of SortOptions

isDescending boolean required

​

field SortField required

​

Values of SortField

CREATED_AT

​

token string

​

archivedStatuses array of ArchivedStatus

Default search status is NOT_ARCHIVED if none are provided. Allows for including archived secrets in search.

Values of ArchivedStatus

NOT_ARCHIVED

​

ARCHIVED

​

Response

results array of Secret

​

Fields of Secret

rid string (RID)

​

name string

​

description string

​

createdBy string (RID)

​

properties map of PropertyName to string

​

labels array of string

​

createdAt string (date-time)

​

isArchived boolean

​

nextPageToken string

​

Request

curl

curl -X POST "https://api.gov.nominal.io/api/secrets/v1/secrets/search" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "query": {
    "type": "searchText",
    "searchText": "<search text>"
  },
  "sort": {
    "isDescending": true,
    "field": "CREATED_AT"
  }
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"type": "searchText", "searchText": "<search text>"},
        "sort": {"isDescending": True, "field": "CREATED_AT"},
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/secrets/v1/secrets/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"type": "searchText", "searchText": "<search text>"},
        "sort": {"isDescending": True, "field": "CREATED_AT"},
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/secrets/v1/secrets/search",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "query": {"type": "searchText", "searchText": "<search text>"},
                "sort": {"isDescending": True, "field": "CREATED_AT"},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "results": [
    {
      "rid": "<secret rid>",
      "name": "<name>",
      "description": "<description>",
      "createdBy": "<created by>",
      "properties": {
        "<key>": "<property value>"
      },
      "labels": [
        "<label>"
      ],
      "createdAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ],
  "nextPageToken": "<token>"
}

Errors

Errors shows how these errors are sent.

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

Status	Name	Notes
404	SecretNotFound
404	SecretsNotFound
500	UnableToEncryptSecret

Types

ArchivedStatus

NOT_ARCHIVED

​

ARCHIVED

​

Property

name string required

​

value string required

​

SearchSecretsQuery

Set type to the name of one of the other fields, and set only that field.

searchText string

​

label string

​

property Property

​

and array of SearchSecretsQuery

​

or array of SearchSecretsQuery

​

workspace string (RID)

​

Secret

rid string (RID) required

​

name string required

​

description string required

​

createdBy string (RID) required

​

properties map of PropertyName to string

​

labels array of string

​

createdAt string (date-time) required

​

isArchived boolean required

​

SortField

CREATED_AT

​

SortOptions

isDescending boolean required

​

field SortField required

​

Page design based on Scalar, MIT License.