> 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.

# Rotate key

POST https://api.customer.com/sarvam/byok/v1/rotate-key

Samvaad calls this endpoint to generate a new Data Encryption Key (DEK). This is part of the key rotation strategy. 
You must return both the new plaintext DEK and its encrypted form (the EDEK) along with the key-alias used for encyption. Samvaad will use this new key for all subsequent encryption operations for the associated data.


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

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: agents
  version: 1.0.0
paths:
  /rotate-key:
    post:
      operationId: generateANewDataEncryptionKeyDek
      summary: Generate a New Data Encryption Key (DEK)
      description: >
        Samvaad calls this endpoint to generate a new Data Encryption Key (DEK).
        This is part of the key rotation strategy. 

        You must return both the new plaintext DEK and its encrypted form (the
        EDEK) along with the key-alias used for encyption. Samvaad will use this
        new key for all subsequent encryption operations for the associated
        data.
      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: >-
            New DEK successfully generated. Returns the new encrypted and
            plaintext DEK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateKeySuccessResponse'
        '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'
        '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 during key generation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
servers:
  - url: https://api.customer.com/sarvam/byok/v1
    description: Production
components:
  schemas:
    RotateKeyBody:
      type: object
      properties:
        encrypted_dek:
          type: string
          description: >-
            The new Base64 encoded Data Encryption Key (DEK), encrypted with the
            master key.
        key_alias:
          type: string
          description: >-
            The alias of the master key that was used for encryption, confirming
            which key was used.
        plaintext_dek:
          type: string
          format: byte
          description: The new Base64 encoded plaintext Data Encryption Key (DEK).
      required:
        - encrypted_dek
        - key_alias
        - plaintext_dek
      description: >-
        The response payload containing the new DEK in both plaintext and
        encrypted forms.
      title: RotateKeyBody
    RotateKeySuccessResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RotateKeyBody'
      required:
        - data
      title: RotateKeySuccessResponse
    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



**Response**

```json
{
  "data": {
    "encrypted_dek": "byok:v1:CiBBRAND+NEW/ENCRYPTED+DATA+STRING",
    "key_alias": "samvaad-prod-master-key-01",
    "plaintext_dek": "VGhpcyBJcyBBIERlY3J5cHRlZCBLZXkgRm9yIFRlc3Rpbmc="
  }
}
```

**SDK Code**

```python
import requests

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

headers = {
    "x-request-id": "x-request-id",
    "x-request-timestamp": "x-request-timestamp",
    "Authorization": "Bearer <token>"
}

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

print(response.json())
```

```javascript
const url = 'https://api.customer.com/sarvam/byok/v1/rotate-key';
const options = {
  method: 'POST',
  headers: {
    'x-request-id': 'x-request-id',
    'x-request-timestamp': 'x-request-timestamp',
    Authorization: 'Bearer <token>'
  }
};

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"
	"net/http"
	"io"
)

func main() {

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

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

	req.Header.Add("x-request-id", "x-request-id")
	req.Header.Add("x-request-timestamp", "x-request-timestamp")
	req.Header.Add("Authorization", "Bearer <token>")

	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/rotate-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>'

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/rotate-key")
  .header("x-request-id", "x-request-id")
  .header("x-request-timestamp", "x-request-timestamp")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.customer.com/sarvam/byok/v1/rotate-key', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    '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/rotate-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>");
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>"
]

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

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