Secrets | Documentation

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 enforces authentication using the API keys you provide in the Basic authentication header.

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

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/secrets

GET /api/v1/secrets HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "created": "text",
      "id": "text",
      "lastUpdated": "text",
      "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:

Fetch the RSA public key from GET /api/v1/secretsPublicKey.
Generate a random AES-256-GCM key (32 bytes) and initialization vector (IV, 12 bytes).
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.
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 enforces authentication using the API keys you provide in the Basic authentication header.

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

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

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": "text",
    "id": "text",
    "lastUpdated": "text",
    "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 enforces authentication using the API keys you provide in the Basic authentication header.

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

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

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": "text",
    "id": "text",
    "lastUpdated": "text",
    "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 enforces authentication using the API keys you provide in the Basic authentication header.

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

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

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

Fetch this public key.
Generate a random AES-256-GCM key (32 bytes) and initialization vector (IV, 12 bytes).
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.
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.
Use the encryptedValue and encryptionKey in the create or update secret request.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

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

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

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"
  }
}

hashtagList secrets

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagCreate a secret

hashtagEncryption

hashtagConstraints

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagUpdate a secret

hashtagEncryption

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagDelete a secret

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagGet the encryption public key

hashtagUsage

hashtagEncryption workflow

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

List secrets

Authentication

Authorization

Tags

Rate limiting

Create a secret

Encryption

Constraints

Authentication

Authorization

Tags

Rate limiting

Update a secret

Encryption

Authentication

Authorization

Tags

Rate limiting

Delete a secret

Authentication

Authorization

Tags

Rate limiting

Get the encryption public key

Usage

Encryption workflow

Authentication

Authorization

Tags

Rate limiting