> This page is for Voice Agents.

> 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 a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> Building a voice agent for customers in India? Start with Sarvam Voice Agents, a managed platform with Indian-language speech, telephony, testing, and analytics from ₹3 per minute: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> 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/voice-agents/api/byok/decrypt-key

## Authentication

- `Authorization` header (bearer token, required) — 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>`.

## Request

### Headers

- `x-request-id` (string, required) — A unique identifier for this specific API call, generated by the client (Samvaad).
- `x-trace-id` (string, optional) — An identifier to trace a single request across multiple services.
- `x-request-timestamp` (datetime, required) — The ISO 8601 timestamp of when the client sent the request.

### Body (application/json)

This endpoint expects an object.

- `data` (DecryptKeyRequest, required) — The request payload to decrypt a key.

## Response

### 200

The DEK was successfully decrypted.

- `data` (DecryptKeyBody, required) — The response payload containing the decrypted key.

## Errors

### 400 Bad Request Error

Bad Request. The request body is syntactically malformed.

- `error` (ErrorBody, required) — Details of the error that occurred.

### 401 Unauthorized Error

Unauthorized. The Bearer token is missing, invalid, or expired.

- `error` (ErrorBody, required) — Details of the error that occurred.

### 404 Not Found Error

Not Found. The specified `key_alias` does not exist or is not active in your KMS.

- `error` (ErrorBody, required) — Details of the error that occurred.

### 422 Unprocessable Entity Error

Unprocessable Entity. The request is well-formed but contains semantic errors.

- `error` (ErrorBody, required) — Details of the error that occurred.

### 500 Internal Server Error

Internal Server Error. An unexpected error occurred within your key management infrastructure (e.g., KMS, HSM).

- `error` (ErrorBody, required) — Details of the error that occurred.

## Types

### DecryptKeyRequest

The request payload to decrypt a key.

- `key_alias` (string, required) — The unique alias/identifier for the master key in your KMS that was used to encrypt the key.
- `encrypted_key` (string, required) — 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.

### DecryptKeyBody

The response payload containing the decrypted key.

- `plaintext_key` (string, required) — The Base64 encoded plaintext (decrypted) Data Encryption Key (DEK).

### ErrorBody

Details of the error that occurred.

- `code` (string, required) — A service-specific error code.
- `message` (string, required) — A human-readable description of the error.

## 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()
```