Discover the New Soda AI – MCP, Autopilot, CLI |
Learn More
Ctrlk
Soda CloudBook a demo
slack
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Secrets

Soda Cloud API Secret Endpoints

List secrets

get
/api/v1/secrets

This endpoint allows you to list secrets in your organization.

This GET is a paginated API that uses the following parameters to request specific details:

  • size: Supply an integer value between 10 and 1000, inclusive. The default value is 10.

  • page: Supply an integer value. The default value is 0.

  • search: Supply a string value to filter secrets by name (case-insensitive partial match).

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Secrets

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Query parameters
pageinteger · int32Optional
searchstringOptional
sizeinteger · int32Optional
Responses
200

Successful response

application/json
firstbooleanRequired
lastbooleanRequired
numberinteger · int32Required
sizeinteger · int32Required
totalElementsinteger · int32Required
totalPagesinteger · int32Required
get/api/v1/secrets
GET /api/v1/secrets HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "created": "2026-01-01T00:00:00.000Z",
      "id": "text",
      "lastUpdated": "2026-01-01T00:00:00.000Z",
      "name": "text"
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}

Create a secret

post
/api/v1/secrets

Creates a new secret in your organization. Secrets store encrypted credentials that can be referenced in datasource configurations using ${secret.NAME} placeholders, keeping sensitive values out of plain text.

Encryption

Secret values must be encrypted client-side before sending them to this endpoint. This enables a zero-trust design, where Soda never decrypts the secret. Decryption happens only during scan execution, within the runner.

Use the GET /api/v1/secretsPublicKey endpoint to obtain the server's RSA public key. The encryption uses a two-layer scheme:

  1. Fetch the RSA public key from GET /api/v1/secretsPublicKey.

  2. Generate a random AES-256-GCM key (32 bytes) and initialization vector (IV, 12 bytes).

  3. Encrypt the secret value using AES-256-GCM with the generated key and IV. Base64-encode the ciphertext and prefix it with encrypted_. This becomes the encryptedValue field.

  4. Export the raw AES key and IV as base64 strings and concatenate them as {base64_key}:::{base64_iv}. Encrypt this string using RSA-OAEP (SHA-256) with the public key from step 1. Base64-encode the result. This becomes the encryptionKey field.

Constraints

  • The secret name must not contain whitespace and must be unique within the organization.

  • Both encryptionKey and encryptedValue are required.

  • The organization must have the contracts feature enabled and the secure store must not be disabled.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Secrets

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
encryptedValuestringRequired
encryptionKeystringRequired
namestringRequired
Responses
200

Successful response

application/json
post/api/v1/secrets
POST /api/v1/secrets HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "encryptedValue": "text",
  "encryptionKey": "text",
  "name": "text"
}
{
  "secret": {
    "created": "2026-01-01T00:00:00.000Z",
    "id": "text",
    "lastUpdated": "2026-01-01T00:00:00.000Z",
    "name": "text"
  }
}

Update a secret

post
/api/v1/secrets/{secretId}

Updates the encrypted value of an existing secret. The secret name cannot be changed.

Both encryptionKey and encryptedValue must be provided together — you cannot update one without the other.

Encryption

The new secret value must be encrypted client-side using the same two-layer encryption scheme as creation. See the POST /api/v1/secrets (Create a secret) endpoint for the full encryption workflow.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Secrets

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
secretIdstringRequired
Body
encryptedValuestringRequired
encryptionKeystringRequired
Responses
200

Successful response

application/json
post/api/v1/secrets/{secretId}
POST /api/v1/secrets/{secretId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "encryptedValue": "text",
  "encryptionKey": "text"
}
{
  "secret": {
    "created": "2026-01-01T00:00:00.000Z",
    "id": "text",
    "lastUpdated": "2026-01-01T00:00:00.000Z",
    "name": "text"
  }
}

Delete a secret

delete
/api/v1/secrets/{secretId}

Deletes an existing secret.

The secret cannot be deleted if it is referenced by a datasource configuration.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Secrets

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
secretIdstringRequired
Responses
200

Successful response

application/json
messagestringOptional
delete/api/v1/secrets/{secretId}
DELETE /api/v1/secrets/{secretId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "message": "text"
}

Get the encryption public key

get
/api/v1/secretsPublicKey

Returns the RSA public key in JWK (JSON Web Key) format, used for client-side encryption of secret values.

Usage

When creating or updating a secret, the secret value must be encrypted client-side before sending it to the API. This endpoint provides the RSA public key needed for that encryption.

Encryption workflow

  1. Fetch this public key.

  2. Generate a random AES-256-GCM key (32 bytes) and initialization vector (IV, 12 bytes).

  3. Encrypt the secret value using AES-256-GCM with the generated key and IV. Base64-encode the ciphertext and prefix it with encrypted_. This becomes the encryptedValue field.

  4. Export the raw AES key and IV as base64 strings and concatenate them as {base64_key}:::{base64_iv}. Encrypt this string using RSA-OAEP (SHA-256) with this public key. Base64-encode the result. This becomes the encryptionKey field.

  5. Use the encryptedValue and encryptionKey in the create or update secret request.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Secrets

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Responses
200

Successful response

application/json
get/api/v1/secretsPublicKey
GET /api/v1/secretsPublicKey HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "encryptionKey": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
PreviousScans
NextUsers

Last updated

Was this helpful?