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

# Security

> How the cNGN API protects every request, and how to handle your credentials

All communication between your application and the cNGN platform is protected end-to-end: AES-256-CBC encryption for request payloads and Ed25519 public-key encryption for response data, on top of API-key authentication and IP whitelisting.

<Warning>
  Safeguard your **encryption key** and **Ed25519 private key** at all times. Never expose them in client-side code, mobile apps, or public repositories. Anyone holding them can read your API traffic.
</Warning>

## The three security layers

<CardGroup cols={3}>
  <Card title="API key" icon="key" href="/guides/authentication">
    A Bearer token identifies your business and selects the test or live environment.
  </Card>

  <Card title="IP whitelisting" icon="shield" href="/guides/authentication#ip-whitelisting">
    Requests are only accepted from server IPs you have whitelisted.
  </Card>

  <Card title="Payload encryption" icon="lock" href="/guides/encryption">
    Request bodies and response data are encrypted in both directions.
  </Card>
</CardGroup>

## Setting up secure communication

<Steps>
  <Step title="Generate API and encryption keys" icon="key">
    Retrieve the auto-generated keys from your merchant dashboard:

    * **API key** (`cngn_test...` or `cngn_live...`): sent as your Bearer token
    * **Encryption key**: used to AES-encrypt request bodies

    Store both in a secrets manager immediately; treat them like passwords.

    <Card title="Guide: Generating API Keys" icon="key" href="/guides/security/generating-api-keys" horizontal>
      Step-by-step dashboard walkthrough.
    </Card>
  </Step>

  <Step title="Generate an Ed25519 SSH key pair" icon="terminal">
    ```bash theme={null}
    ssh-keygen -t ed25519 -C "api@yourcompany.com" -f cngn_api_key
    ```

    This creates two files:

    | File               | Role                                  | Handling                 |
    | ------------------ | ------------------------------------- | ------------------------ |
    | `cngn_api_key`     | Private key, decrypts API responses   | Keep on your server only |
    | `cngn_api_key.pub` | Public key, encrypts responses to you | Upload to the dashboard  |

    <Card title="Guide: Generating SSH Keys" icon="terminal" href="/guides/security/generating-ssh-keys" horizontal>
      Key generation and clipboard commands for macOS, Linux, and Windows.
    </Card>
  </Step>

  <Step title="Upload the public key to your dashboard" icon="upload">
    Upload `cngn_api_key.pub` to the SSH key slot for the matching environment. Each environment (test and live) has its own slot; requests fail with `No Test SSH Key found` or `No Live SSH Key found` if the slot is empty.
  </Step>

  <Step title="Encrypt requests and decrypt responses" icon="lock">
    Wire the crypto into your integration, or let an [official SDK](/sdks) do it for you:

    * Encrypt every `POST`/`PUT` body into the `{content, iv}` format
    * Decrypt the `data` field of every response with your private key

    Full code for both directions is in the [Encryption guide](/guides/encryption).
  </Step>
</Steps>

## Credential handling rules

| Credential          | Share with cNGN?            | Commit to git? | Client-side? |
| ------------------- | --------------------------- | -------------- | ------------ |
| API key             | Never (dashboard issues it) | Never          | Never        |
| Encryption key      | Never (dashboard issues it) | Never          | Never        |
| Ed25519 private key | Never                       | Never          | Never        |
| Ed25519 public key  | Yes, via dashboard upload   | Acceptable     | Acceptable   |

## Best practices

<AccordionGroup>
  <Accordion title="Store secrets in a secrets manager" icon="vault">
    Use a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) rather than environment files checked into repositories. Scope read access to the services that call the API.
  </Accordion>

  <Accordion title="Rotate keys on exposure or staff changes" icon="rotate">
    If a key may have leaked, or someone with access leaves the team, regenerate the API and encryption keys in the dashboard and replace the SSH key pair. Old keys stop working the moment new ones are issued.
  </Accordion>

  <Accordion title="Keep the IP whitelist tight" icon="list-check">
    Whitelist only the egress IPs that actually call the API, and remove entries when infrastructure is decommissioned. A short list limits the blast radius of a leaked key, since requests from other IPs are rejected.
  </Accordion>

  <Accordion title="Separate test and live credentials" icon="flask">
    Never point production services at `cngn_test` keys or vice versa. Keep the two credential sets in separate secret scopes so a misconfiguration cannot cross environments.
  </Accordion>

  <Accordion title="Monitor for anomalies" icon="chart-line">
    Watch your [transaction history](/api-reference/get-transactions) for transfers you did not initiate, and alert on repeated `403` or `Decryption failed` responses, which can indicate probing.
  </Accordion>
</AccordionGroup>

<Check>
  Keys generated, public key uploaded, secrets locked away? Continue to the [Encryption guide](/guides/encryption) to wire up the payload crypto, then verify everything with the [Going Live Checklist](/going-live).
</Check>