> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Encryption

> Deck provides full or partial payload encryption for API requests, responses, and webhooks to secure sensitive data in transit and at rest.

We use **AES-256-GCM** - a symmetric encryption algorithm combining Advanced Encryption Standard with a 256-bit key length and Galois/Counter Mode (GCM).

## Setup

### Enabling Encryption

<Steps>
  <Step title="Enable Encryption">
    Turn on payload encryption in the <a href="https://dashboard.deck.co" target="_blank">Deck Dashboard</a>.
  </Step>

  <Step title="Configure Encryption">
    Choose to encrypt your requests, responses, or both.
  </Step>

  <Step title="Find Your Keys">
    Find your Encryption Key in the API Keys section of the <a href="https://dashboard.deck.co" target="_blank">Dashboard</a>.
  </Step>
</Steps>

### Configuration Options

You can configure encryption for:

* **Request encryption**: Full payload or input field only
* **Response encryption**: API responses and webhook payloads

## Encryption Modes

### Full Payload Encryption

Encrypt the entire request or response payload:

```json theme={null}
{
    "encrypted_payload": "base64_encoded_encrypted_data", 
    "encryption_version": "1.0"
}
```

`encrypted_payload`: The encrypted Base64-encoded payload

### Input Field Encryption

For `/jobs/submit` requests, encrypt only the input field:

```json theme={null}
{
    "job_code": "EnsureConnection",
    "input": "base64_encoded_encrypted_data"
}
```

## Implementation

### Sending Encrypted Requests

<CodeGroup>
  ```bash Full Payload Encryption theme={null}
  # Original unencrypted payload:
  # {
  #   "job_code": "EnsureConnection",
  #   "input": {
  #     "source_guid": "11115055-46cf-4e49-6ba4-08ddcbf23235",
  #     "username": "user123",
  #     "password": "password123"
  #   }
  # }

  curl --location 'https://live.deck.co/api/v1/jobs/submit' \
  --header 'x-deck-client-id: your_client_id' \
  --header 'x-deck-secret: your_secret' \
  --header 'Content-Type: application/json+encrypted' \
  --data '{
    "encrypted_payload": "il0hAWW83PG7ZwHkeLQzJRn8X01RNdyK8DI86jkZJTLjkYdOTQfhVn/y/dsAU+6D0T0ODgKCcNxoGqUs5Z+cvei3+3J99XP3bOXGzxwL6ZaNpO5f7YotVBHBimqtHpNceEP9s2Kahvk/v1MMf0NQRKA7H4mz2dXyyiU3+mDIMQOPO9dBF2omZTNS1lOOsrfWL1YDDBISIN8i86jb5dzVSXnTfAxclZDWnofLY4DfO2dZ0pNAfRd/a2qkyaf/AEhepmHlURM=",
    "encryption_version": "1.0"
  }'
  ```

  ```bash Input Field Encryption theme={null}
  # Original unencrypted payload:
  # {
  #   "job_code": "EnsureConnection",
  #   "input": {
  #     "source_guid": "11115055-46cf-4e49-6ba4-08ddcbf23235",
  #     "username": "user123",
  #     "password": "password123"
  #   }
  # }

  curl --location 'https://live.deck.co/api/v1/jobs/submit' \
  --header 'x-deck-client-id: your_client_id' \
  --header 'x-deck-secret: your_secret' \
  --header 'Content-Type: application/json+encrypted' \
  --data '{
    "job_code": "EnsureConnection",
    "input": "mhK3Mc4qXdOjvNsjOASSgwbDk33HxySsPQo5FYPLOzSqyZHFjBFMesA3v31qyTHWWzcC7eGMQQSKsCp6/z3LATYD5tD+0eU9m2vOC/CYYKh78UcVHe07lpTeeZUs9Uc5vm/m77yKRw=="
  }'
  ```
</CodeGroup>

### Receiving Encrypted Responses

<CodeGroup>
  ```json API Response theme={null}
  # Encrypted response:
  {
      "encrypted_payload": "rpcnQBAb0k+6ctcXyRgfk06WhCyHTxv+xNMKjCIdiue9U5b97AfM2a+OIJRkpQ2kPqh4WIOQ81nL3wczRUwLa6+9/2gSIqNb42Pr+osmuKkdibkC49ip1GGz2HNH4dq76G4vsPx3Hs728Sc3QQ==",
      "encryption_version": "1.0"
  }

  # Decrypted content:
  {
      "job_guid": "834fb49c-5ebb-4f7c-775b-08ddcbf231fd",
      "job_code": "EnsureConnection"
  }
  ```

  ```json Webhook theme={null}
  # Encrypted webhook:
  {
      "encrypted_payload": "1lA5uxL+GP5s60rY5FKB+e0MJrpg/pXNONllcP7ZleQroatAyCXgVTx0gSbuWtQJfxkR8Qqtq9Q40iQ+zuUaERw0x48XXh6IRI0XV+m4MH3lEVLuvBMvMqvslDyRXhign+UAgZXQ0pq3D1BJcc3Xjx4k8SFhTU4eLJHZf3M9Ba8BenyE59poJW6OUZHaTIq67/HPjn41jQEwovci4APz1QELfqI4jEQd+tsn7ytSNrxKckiPxGIxC8QRD6YvN4ZEe/SIgGQfvGvmUNwDILbT8GCbvGoOK6vy3mRhsSjNB8bhRXy2DhcRakmC63vOBqpF2QB0QCXcgPUI/daM1LU=",
      "encryption_version": "1.0"
  }

  # Decrypted content:
  {
      "job_guid": "11113ac3-2222-4e97-d9ad-3333cb148249",
      "output": {
          "access_token": "access-production-11112222-3333-4444-5555-666666666666"
      },
      "webhook_type": "Job",
      "webhook_code": "EnsureConnection",
      "environment": "Production"
  }
  ```
</CodeGroup>

## Decryption

### Key Requirements

* **Algorithm**: AES-256-GCM
* **Key**: Use the encryption key provided by Deck in the Dashboard
* **Format**: Base64-encoded encrypted data
* **Structure**: `nonce + ciphertext + tag` (combined and base64-encoded)

### Decryption Steps

<Steps>
  <Step title="Extract the encrypted payload">
    Get the `encrypted_payload` field from the API response or webhook
  </Step>

  <Step title="Base64 decode">
    Decode the base64-encoded encrypted payload to get the raw bytes
  </Step>

  <Step title="Split the components">
    <ul>
      <li>First 12 bytes: nonce</li>
      <li>Last 16 bytes: authentication tag</li>
      <li>Middle: ciphertext</li>
    </ul>
  </Step>

  <Step title="Decrypt using AES-256-GCM">
    Use your encryption key to decrypt the ciphertext with the nonce and tag
  </Step>

  <Step title="Parse the JSON">
    Convert the decrypted bytes to a string and parse as JSON to get the original data
  </Step>
</Steps>