Authentication

Overview

Synap uses API keys for all SDK authentication. Set your key and your instance id as environment variables and you are done.

export SYNAP_API_KEY="synap_your_key_here"
export SYNAP_INSTANCE_ID="inst_your_instance_id"

$env:SYNAP_API_KEY = "synap_your_key_here"
$env:SYNAP_INSTANCE_ID = "inst_your_instance_id"

[System.Environment]::SetEnvironmentVariable("SYNAP_API_KEY", "synap_your_key_here", "User")
[System.Environment]::SetEnvironmentVariable("SYNAP_INSTANCE_ID", "inst_your_instance_id", "User")

SYNAP_API_KEY=synap_your_key_here
SYNAP_INSTANCE_ID=inst_your_instance_id

The SDK authenticates every request to Synap Cloud using your API key. SYNAP_INSTANCE_ID is optional, and the dashboard gives you both together so you can paste them in one go.

Set the instance id as an environment variable, not as a constructor argument. SYNAP_INSTANCE_ID records which instance you are on and leaves the SDK keyed on your credential. Passing instance_id= to MaximemSynapSDK(...) is different: it makes the id the identity, so a second key used under it is silently discarded and key rotation stops taking effect. See Singleton Pattern.

Getting your API key

Log in to the Synap Dashboard
Navigate to your instance
Click API Keys in the instance detail page
Click Generate API Key, give it a label, and copy the key

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

API keys start with synap_ and look like this:

synap_Bx7Kp2mN9vQ4rT6wY8zA1cE3fG5hJ7kLm0pR2sT4uV6wX8yZ0aB1cD3eF5g

Using the API key

Option 1: Environment variable (recommended)

Set SYNAP_API_KEY and SYNAP_INSTANCE_ID:

export SYNAP_API_KEY="synap_your_key_here"
export SYNAP_INSTANCE_ID="inst_your_instance_id"

$env:SYNAP_API_KEY = "synap_your_key_here"
$env:SYNAP_INSTANCE_ID = "inst_your_instance_id"

[System.Environment]::SetEnvironmentVariable("SYNAP_API_KEY", "synap_your_key_here", "User")
[System.Environment]::SetEnvironmentVariable("SYNAP_INSTANCE_ID", "inst_your_instance_id", "User")

SYNAP_API_KEY=synap_your_key_here
SYNAP_INSTANCE_ID=inst_your_instance_id

The SDK reads these automatically:

from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK()
await sdk.initialize()

import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient();
await sdk.initialize();

import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient();
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:

sdk = MaximemSynapSDK(
    api_key="synap_your_key_here"
)
await sdk.initialize()

const sdk = new SynapClient({
  apiKey: 'synap_your_key_here',
});
await sdk.initialize();

const sdk = new SynapClient({
  apiKey: 'synap_your_key_here',
});
await sdk.initialize();

Priority order

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

The constructor parameter (api_key= in Python, apiKey in JavaScript)
SYNAP_API_KEY environment variable

The first one that succeeds wins. If neither is available, initialize() raises an AuthenticationError. The instance id resolves the same way (instance_id= / instanceId, then SYNAP_INSTANCE_ID), but it is optional: if neither is set, initialize() resolves it from your API key. Setting it changes nothing about which instance you reach, since the key already determines that.

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.

These patterns each put one key in one process, which is what you want. If a single process uses two keys that belong to the same instance, you get two independent SDKs rather than one shared one, and initialize() warns you about it. See Two keys, one instance.

In JavaScript, credentials resolve identically and the SDK reads SYNAP_API_KEY from process.env on every runtime that exposes it, Edge and Workers included. See Where it runs.

Security best practices

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.

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.

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.

Serverless and edge deployments

API keys work everywhere: Vercel, AWS Lambda, Cloudflare Workers, Docker, Kubernetes. Set SYNAP_API_KEY in your platform’s environment configuration and you’re done. No file I/O, no extra setup step.

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?

Setup

SDK Guide

Overview

Getting your API key

Using the API key

Option 1: Environment variable (recommended)

Option 2: Constructor parameter

Priority order

Multiple keys per instance

Security best practices

Troubleshooting

​Overview

​Getting your API key

​Using the API key

​Option 1: Environment variable (recommended)

​Option 2: Constructor parameter

​Priority order

​Multiple keys per instance

​Security best practices

​Troubleshooting

Overview

Getting your API key

Using the API key

Option 1: Environment variable (recommended)

Option 2: Constructor parameter

Priority order

Multiple keys per instance

Security best practices

Troubleshooting