> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt.
> For full documentation content in one file, see https://docs.sarvam.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# Decrypt key

POST https://api.customer.com/sarvam/byok/v1/decrypt-key
Content-Type: application/json

Samvaad calls this endpoint to decrypt an Encrypted Data Encryption Key (EDEK) using the corresponding master key in your Key Management System (KMS) or HSM.

The plaintext key is then cached securely in memory by Samvaad for a short, configurable duration to perform data encryption and decryption operations. The `key_alias` is used to identify which master key should be used for decryption.


Reference: https://docs.sarvam.ai/conversations/api/byok/decrypt-key

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: agents
  version: 1.0.0
paths:
  /decrypt-key:
    post:
      operationId: decryptAnEncryptedDataEncryptionKeyDek
      summary: Decrypt an Encrypted Data Encryption Key (DEK)
      description: >
        Samvaad calls this endpoint to decrypt an Encrypted Data Encryption Key
        (EDEK) using the corresponding master key in your Key Management System
        (KMS) or HSM.


        The plaintext key is then cached securely in memory by Samvaad for a
        short, configurable duration to perform data encryption and decryption
        operations. The `key_alias` is used to identify which master key should
        be used for decryption.
      tags:
        - keyManagement
      parameters:
        - name: Authorization
          in: header
          description: |
            A token sent in the `Authorization` header.

            This can be one of two types:
            1. A short-lived **JWT** obtained from the `/auth` endpoint.
            2. A long-lived, static **API Key** provided during setup.

            In both cases, the header format is `Authorization: Bearer <token>`.
          required: true
          schema:
            type: string
        - name: x-request-id
          in: header
          description: >-
            A unique identifier for this specific API call, generated by the
            client (Samvaad).
          required: true
          schema:
            type: string
            format: uuid
        - name: x-trace-id
          in: header
          description: An identifier to trace a single request across multiple services.
          required: false
          schema:
            type: string
            format: uuid
        - name: x-request-timestamp
          in: header
          description: The ISO 8601 timestamp of when the client sent the request.
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: The DEK was successfully decrypted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecryptKeySuccessResponse'
        '400':
          description: Bad Request. The request body is syntactically malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. The Bearer token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Not Found. The specified `key_alias` does not exist or is not active
            in your KMS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Unprocessable Entity. The request is well-formed but contains
            semantic errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >-
            Internal Server Error. An unexpected error occurred within your key
            management infrastructure (e.g., KMS, HSM).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: The request containing the key alias and the encrypted key data.
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/DecryptKeyRequest'
              required:
                - data
servers:
  - url: https://api.customer.com/sarvam/byok/v1
    description: Production
components:
  schemas:
    DecryptKeyRequest:
      type: object
      properties:
        key_alias:
          type: string
          description: >-
            The unique alias/identifier for the master key in your KMS that was
            used to encrypt the key.
        encrypted_key:
          type: string
          description: >
            The Base64 encoded, encrypted Data Encryption Key (EDEK).

            The value will be prefixed with a version marker, e.g., `byok:v1:`.
            Your service should be prepared to handle this format.
      required:
        - key_alias
        - encrypted_key
      description: The request payload to decrypt a key.
      title: DecryptKeyRequest
    DecryptKeyBody:
      type: object
      properties:
        plaintext_key:
          type: string
          format: byte
          description: The Base64 encoded plaintext (decrypted) Data Encryption Key (DEK).
      required:
        - plaintext_key
      description: The response payload containing the decrypted key.
      title: DecryptKeyBody
    DecryptKeySuccessResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DecryptKeyBody'
      required:
        - data
      title: DecryptKeySuccessResponse
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: A service-specific error code.
        message:
          type: string
          description: A human-readable description of the error.
      required:
        - code
        - message
      description: Details of the error that occurred.
      title: ErrorBody
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
        - error
      description: A standard wrapper for all error responses.
      title: ErrorResponse
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        A token sent in the `Authorization` header.

        This can be one of two types:
        1. A short-lived **JWT** obtained from the `/auth` endpoint.
        2. A long-lived, static **API Key** provided during setup.

        In both cases, the header format is `Authorization: Bearer <token>`.

```

## Examples



**Request**

```json
{
  "data": {
    "key_alias": "samvaad-prod-master-key-01",
    "encrypted_key": "byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING"
  }
}
```

**Response**

```json
{
  "data": {
    "plaintext_key": "VGhpcyBJcyBBIERlY3J5cHRlZCBLZXkgRm9yIFRlc3Rpbmc="
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.customer.com/sarvam/byok/v1/decrypt-key"

payload = { "data": {
        "key_alias": "samvaad-prod-master-key-01",
        "encrypted_key": "byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING"
    } }
headers = {
    "x-request-id": "x-request-id",
    "x-request-timestamp": "x-request-timestamp",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.customer.com/sarvam/byok/v1/decrypt-key';
const options = {
  method: 'POST',
  headers: {
    'x-request-id': 'x-request-id',
    'x-request-timestamp': 'x-request-timestamp',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"data":{"key_alias":"samvaad-prod-master-key-01","encrypted_key":"byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.customer.com/sarvam/byok/v1/decrypt-key"

	payload := strings.NewReader("{\n  \"data\": {\n    \"key_alias\": \"samvaad-prod-master-key-01\",\n    \"encrypted_key\": \"byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-request-id", "x-request-id")
	req.Header.Add("x-request-timestamp", "x-request-timestamp")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.customer.com/sarvam/byok/v1/decrypt-key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-request-id"] = 'x-request-id'
request["x-request-timestamp"] = 'x-request-timestamp'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"key_alias\": \"samvaad-prod-master-key-01\",\n    \"encrypted_key\": \"byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.customer.com/sarvam/byok/v1/decrypt-key")
  .header("x-request-id", "x-request-id")
  .header("x-request-timestamp", "x-request-timestamp")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"key_alias\": \"samvaad-prod-master-key-01\",\n    \"encrypted_key\": \"byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.customer.com/sarvam/byok/v1/decrypt-key', [
  'body' => '{
  "data": {
    "key_alias": "samvaad-prod-master-key-01",
    "encrypted_key": "byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'x-request-id' => 'x-request-id',
    'x-request-timestamp' => 'x-request-timestamp',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.customer.com/sarvam/byok/v1/decrypt-key");
var request = new RestRequest(Method.POST);
request.AddHeader("x-request-id", "x-request-id");
request.AddHeader("x-request-timestamp", "x-request-timestamp");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"data\": {\n    \"key_alias\": \"samvaad-prod-master-key-01\",\n    \"encrypted_key\": \"byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-request-id": "x-request-id",
  "x-request-timestamp": "x-request-timestamp",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["data": [
    "key_alias": "samvaad-prod-master-key-01",
    "encrypted_key": "byok:v1:CiBQ EXEMPLARY/ENCRYPTED+DATA+STRING"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.customer.com/sarvam/byok/v1/decrypt-key")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```