Secret

Method	Path	Description
GET	`/api/v1/secrets/{workspace}/{secretId}/value`	Get secret value
PUT	`/api/v1/secrets/{workspace}/{secretId}/value`	Set secret value
POST	`/api/v1/secrets/{workspace}/pubkey`	Get encryption public key
GET	`/api/v1/secrets/{workspace}`	List secrets
GET	`/api/v1/secrets/{workspace}/{secretId}`	Get secret

Get secret value

GET /api/v1/secrets/{workspace}/{secretId}/value

Get a secret's encrypted value. Client provides ephemeral public key for E2E encryption. Rate limited to 100 requests per user per workspace per hour.

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`secretId`	Yes	Secret ID

Query Parameters

Name	Required	Type	Description
`X-Ephemeral-Pubkey`	Yes	`string`	Base64-encoded X25519 ephemeral public key (32 bytes)

Responses

Status	Description
`200`	Secret value retrieved successfully (E2E encrypted)
`400`	Invalid or missing ephemeral public key
`403`	Not authorized to read secret
`404`	Secret not found or has no value
`429`	Rate limit exceeded

Response Shape

Field	Type	Description
`encryptedValue`	`string`	Base64-encoded encrypted value (XChaCha20-Poly1305 ciphertext)
`nonce`	`string`	Base64-encoded 24-byte nonce used for encryption
`serverPublicKey`	`string`	Base64-encoded server ephemeral X25519 public key
`algorithm`	`string`	Encryption algorithm identifier

Example Response

{
  "success": true,
  "data": {
    "encryptedValue": "string",
    "nonce": "string",
    "serverPublicKey": "string",
    "algorithm": "string"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/secrets/my-workspace/<secretId>/value" \
  -H "Authorization: Bearer <your-token>"

Set secret value

PUT /api/v1/secrets/{workspace}/{secretId}/value

Set or update a secret's value using E2E encryption

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`secretId`	Yes	Secret ID

Request Body

Content-Type: application/json

Field	Type	Description
`encryptedValue`	`string`	Base64-encoded encrypted value (XChaCha20-Poly1305 ciphertext)
`nonce`	`string`	Base64-encoded 24-byte nonce used for encryption
`clientPublicKey`	`string`	Base64-encoded client ephemeral X25519 public key (32 bytes)
`keyId`	`string`	Key ID from /pubkey response to retrieve server's private key

Responses

Status	Description
`204`	Secret value set successfully
`400`	Invalid request
`403`	Not authorized to write secret
`404`	Secret not found

Example

curl -X PUT "https://poliglot.io/api/v1/secrets/my-workspace/<secretId>/value" \
  -H "Authorization: Bearer <your-token>"
  -H "Content-Type: application/json" \
  -d '{}'

Get encryption public key

POST /api/v1/secrets/{workspace}/pubkey

Get server's ephemeral public key for E2E encrypting secret values. Key expires after 5 minutes.

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug

Responses

Status	Description
`200`	Public key generated successfully
`404`	Workspace not found

Response Shape

Field	Type	Description
`serverPublicKey`	`string`	Base64-encoded server ephemeral X25519 public key (32 bytes)
`keyId`	`string`	Unique identifier to reference this key in subsequent requests
`algorithm`	`string`	Encryption algorithm identifier
`expiresAt`	`string (date-time)`	ISO 8601 timestamp when this key expires

Example Response

{
  "success": true,
  "data": {
    "serverPublicKey": "string",
    "keyId": "string",
    "algorithm": "string",
    "expiresAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X POST "https://poliglot.io/api/v1/secrets/my-workspace/pubkey" \
  -H "Authorization: Bearer <your-token>"

List secrets

GET /api/v1/secrets/{workspace}

List all secrets in a workspace, optionally filtered by URI prefix

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug

Query Parameters

Name	Required	Type	Description
`prefix`	No	`string`	Optional URI prefix to filter secrets
`page`	No	`integer(int32)`	Page number (0-indexed)
`size`	No	`integer(int32)`	Page size (max 100)

Responses

Status	Description
`200`	Secrets retrieved successfully
`403`	Not authorized to read workspace
`404`	Workspace not found

Response Shape

Field	Type	Description
`id`	`string (uuid)`	Secret ID
`uri`	`string`	Secret URI identifier
`description`	`string`	Human-readable description of the secret
`hasValue`	`boolean`	Whether the secret has a value set
`createdAt`	`string (date-time)`	When the secret was created
`updatedAt`	`string (date-time)`	When the secret was last updated
`lastAccessedAt`	`string (date-time)`	When the secret value was last accessed
`accessCount`	`integer (int64)`	Number of times the secret value has been accessed
`matrix`	`MatrixResponse`	Response object containing complete matrix metadata

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uri": "string",
    "description": "string",
    "hasValue": true,
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z",
    "lastAccessedAt": "2025-03-28T14:22:03Z",
    "accessCount": 0,
    "matrix": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "uri": "string",
      "name": "string",
      "description": "string",
      "repositoryUrl": "string",
      "imports": [
        {
          "id": null,
          "uri": null,
          "name": null
        }
      ],
      "importedBy": [
        {
          "id": null,
          "uri": null,
          "name": null
        }
      ],
      "packageInfo": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "string",
        "currentVersion": "string"
      },
      "createdAt": "2025-03-28T14:22:03Z",
      "updatedAt": "2025-03-28T14:22:03Z",
      "prefixDeclarations": [
        {
          "prefix": null,
          "namespaceUri": null
        }
      ]
    }
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/secrets/my-workspace" \
  -H "Authorization: Bearer <your-token>"

Get secret

GET /api/v1/secrets/{workspace}/{secretId}

Get a secret's metadata by ID

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`secretId`	Yes	Secret ID

Responses

Status	Description
`200`	Secret retrieved successfully
`403`	Not authorized to read secret
`404`	Secret not found

Response Shape

Field	Type	Description
`id`	`string (uuid)`	Secret ID
`uri`	`string`	Secret URI identifier
`description`	`string`	Human-readable description of the secret
`hasValue`	`boolean`	Whether the secret has a value set
`createdAt`	`string (date-time)`	When the secret was created
`updatedAt`	`string (date-time)`	When the secret was last updated
`lastAccessedAt`	`string (date-time)`	When the secret value was last accessed
`accessCount`	`integer (int64)`	Number of times the secret value has been accessed
`matrix`	`MatrixResponse`	Response object containing complete matrix metadata

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uri": "string",
    "description": "string",
    "hasValue": true,
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z",
    "lastAccessedAt": "2025-03-28T14:22:03Z",
    "accessCount": 0,
    "matrix": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "uri": "string",
      "name": "string",
      "description": "string",
      "repositoryUrl": "string",
      "imports": [
        {
          "id": null,
          "uri": null,
          "name": null
        }
      ],
      "importedBy": [
        {
          "id": null,
          "uri": null,
          "name": null
        }
      ],
      "packageInfo": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "string",
        "currentVersion": "string"
      },
      "createdAt": "2025-03-28T14:22:03Z",
      "updatedAt": "2025-03-28T14:22:03Z",
      "prefixDeclarations": [
        {
          "prefix": null,
          "namespaceUri": null
        }
      ]
    }
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/secrets/my-workspace/<secretId>" \
  -H "Authorization: Bearer <your-token>"

On this page