# Secrets service

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

OpenAPI file: [`SecretService.json`](https://dev.nominal.io/api/_downloads/387d3789a07e941a82277394ffc14d06/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**

```shell
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**

```python
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**

```python
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**

```python
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`

```json
{
  "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**

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

**requests**

```python
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**

```python
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**

```python
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`

```json
{
  "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**

```shell
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**

```python
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**

```python
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**

```python
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`

```json
{
  "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**

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

**requests**

```python
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**

```python
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**

```python
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`](https://dev.nominal.io/api/rest/secrets-service.md#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**

```shell
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**

```python
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**

```python
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**

```python
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`

```json
{
  "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**

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

**requests**

```python
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**

```python
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**

```python
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**

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

**requests**

```python
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**

```python
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**

```python
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`](https://dev.nominal.io/api/rest/secrets-service.md#searchsecretsquery) required
:   ​

    **searchText**

    Set `type` to `"searchText"`.

    `searchText` string
    :   ​

    **label**

    Set `type` to `"label"`.

    `label` string
    :   ​

    **property**

    Set `type` to `"property"`.

    `property` [`Property`](https://dev.nominal.io/api/rest/secrets-service.md#property)
    :   ​

        Fields of `Property`

        `name` string required
        :   ​

        `value` string required
        :   ​

    **and**

    Set `type` to `"and"`.

    `and` array of [`SearchSecretsQuery`](https://dev.nominal.io/api/rest/secrets-service.md#searchsecretsquery)
    :   ​

    **or**

    Set `type` to `"or"`.

    `or` array of [`SearchSecretsQuery`](https://dev.nominal.io/api/rest/secrets-service.md#searchsecretsquery)
    :   ​

    **workspace**

    Set `type` to `"workspace"`.

    `workspace` string (RID)
    :   ​

`pageSize` integer
:   Defaults to 100. Will throw if larger than 1000.

`sort` [`SortOptions`](https://dev.nominal.io/api/rest/secrets-service.md#sortoptions) required
:   ​

    Fields of `SortOptions`

    `isDescending` boolean required
    :   ​

    `field` [`SortField`](https://dev.nominal.io/api/rest/secrets-service.md#sortfield) required
    :   ​

        Values of `SortField`

        `CREATED_AT`
        :   ​

`token` string
:   ​

`archivedStatuses` array of [`ArchivedStatus`](https://dev.nominal.io/api/rest/secrets-service.md#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`](https://dev.nominal.io/api/rest/secrets-service.md#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**

```shell
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**

```python
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**

```python
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**

```python
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`

```json
{
  "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](https://dev.nominal.io/api/legacy.md#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`](https://dev.nominal.io/api/rest/secrets-service.md#property)
:   ​

`and` array of [`SearchSecretsQuery`](https://dev.nominal.io/api/rest/secrets-service.md#searchsecretsquery)
:   ​

`or` array of [`SearchSecretsQuery`](https://dev.nominal.io/api/rest/secrets-service.md#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`](https://dev.nominal.io/api/rest/secrets-service.md#sortfield) required
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.