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

# Authentication

> How to authenticate your SDK with Synap Cloud using API keys.

## Overview

Synap uses **API keys** for all SDK authentication. One key, one environment variable. That's all you need.

<CodeGroup>
  ```bash Linux / macOS theme={null}
  export SYNAP_API_KEY="synap_your_key_here"
  ```

  ```powershell Windows (PowerShell, session) theme={null}
  $env:SYNAP_API_KEY = "synap_your_key_here"
  ```

  ```powershell Windows (PowerShell, persistent) theme={null}
  [System.Environment]::SetEnvironmentVariable("SYNAP_API_KEY", "synap_your_key_here", "User")
  ```

  ```ini .env file (with python-dotenv) theme={null}
  SYNAP_API_KEY=synap_your_key_here
  ```
</CodeGroup>

The SDK authenticates every request to Synap Cloud using your API key.

## Getting your API key

1. Log in to the [Synap Dashboard](https://synap.maximem.ai)
2. Navigate to your instance
3. Click **API Keys** in the instance detail page
4. Click **Generate API Key**, give it a label, and copy the key

<Warning>
  The key is displayed **only once**. Copy it immediately. If you lose it, revoke it and generate a new one.
</Warning>

API keys start with `synap_` and look like this:

```
synap_Bx7Kp2mN9vQ4rT6wY8zA1cE3fG5hJ7kLm0pR2sT4uV6wX8yZ0aB1cD3eF5g
```

## Using the API key

### Option 1: Environment variable (recommended)

Set `SYNAP_API_KEY`:

<CodeGroup>
  ```bash Linux / macOS theme={null}
  export SYNAP_API_KEY="synap_your_key_here"
  ```

  ```powershell Windows (PowerShell, session) theme={null}
  $env:SYNAP_API_KEY = "synap_your_key_here"
  ```

  ```powershell Windows (PowerShell, persistent) theme={null}
  [System.Environment]::SetEnvironmentVariable("SYNAP_API_KEY", "synap_your_key_here", "User")
  ```

  ```ini .env file (with python-dotenv) theme={null}
  SYNAP_API_KEY=synap_your_key_here
  ```
</CodeGroup>

The SDK reads these automatically:

```python theme={null}
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK()
await sdk.initialize()
```

This is the recommended approach for all environments: local development, CI/CD, Docker, Kubernetes, Vercel, AWS Lambda.

### Option 2: Constructor parameter

Pass the key directly:

```python theme={null}
sdk = MaximemSynapSDK(
    api_key="synap_your_key_here"
)
await sdk.initialize()
```

## Priority order

When `initialize()` is called, the SDK resolves credentials in this order:

1. `api_key` parameter passed to the constructor
2. `SYNAP_API_KEY` environment variable

The first one that succeeds wins. If neither is available, `initialize()` raises an `AuthenticationError`.

## Multiple keys per instance

You can generate multiple API keys for the same instance. Each key has a label and can be revoked independently. Common patterns:

| Label        | Usage                       |
| ------------ | --------------------------- |
| `production` | Your production servers     |
| `staging`    | Staging/preview environment |
| `ci`         | CI/CD pipeline              |
| `dev-alice`  | Developer's local machine   |
| `dev-bob`    | Another developer           |

Revoke any key without affecting the others.

## JavaScript SDK

<Note>
  The JavaScript SDK is a wrapper around the Python SDK and requires a Python 3.11+ runtime on the host. Edge Runtime, Cloudflare Workers, Bun, Deno Deploy, and AWS Lambda Node-only runtimes are **not supported**. See [Installation → JavaScript / TypeScript SDK](/setup/installation#javascript-typescript-sdk).
</Note>

Same pattern: set the environment variable or pass directly:

```javascript theme={null}
const { createClient } = require('@maximem/synap-js-sdk');

// From environment (reads SYNAP_API_KEY automatically)
const client = createClient();
await client.init();

// Or pass directly
const client = createClient({
  apiKey: 'synap_your_key_here',
});
await client.init();
```

## Security best practices

<AccordionGroup>
  <Accordion title="Never commit API keys to version control">
    Use `.env` files (added to `.gitignore`) or your platform's secrets manager. GitHub's secret scanning will flag leaked `synap_` keys automatically.
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Generate a different key for development, staging, CI, and production. If one leaks, revoke only that key; the others continue working.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Generate a new key, update your environment, verify it works, then revoke the old one. There's no expiry deadline; rotate on your own schedule.
  </Accordion>

  <Accordion title="Serverless and edge deployments">
    API keys work everywhere: Vercel, AWS Lambda (Python 3.11+ on host required), Docker, Kubernetes. Set `SYNAP_API_KEY` in your platform's environment configuration and you're done. No file I/O, no extra setup step.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Error                                         | Cause                               | Fix                                                           |
| --------------------------------------------- | ----------------------------------- | ------------------------------------------------------------- |
| `AuthenticationError: No Synap API key found` | SDK can't find credentials anywhere | Set `SYNAP_API_KEY` env var or pass `api_key=` to constructor |
| `AuthenticationError: Invalid credentials`    | Key is wrong, revoked, or malformed | Check the key in your dashboard; is it active?                |