Skip to main content

​
Overview

Synap supports two authentication mechanisms that work together:
MechanismUsed forHow it works
API KeysREST API calls (ingestion, retrieval, management)Passed as a Bearer token in the Authorization header
mTLS CertificatesgRPC streaming connectionsMutual TLS where both client and server present certificates
Both are obtained automatically after the initial bootstrap. You only need to provide a bootstrap key once — the SDK handles everything else.

​
Authentication flow

1

Bootstrap (one-time)

When the SDK initializes for the first time, it presents the bootstrap key to Synap Cloud. The cloud validates the key and, if valid:
  1. Issues an API key for REST calls
  2. Issues an mTLS client certificate (if gRPC is enabled)
  3. Binds both credentials to the instance identity
  4. Marks the bootstrap key as consumed (single-use)
# Bootstrap happens automatically during initialize()
sdk = MaximemSynapSDK(
    instance_id="inst_a1b2c3d4e5f67890",
    bootstrap_token="bk_a1b2c3d4..."  # Single-use bootstrap key
)
await sdk.initialize()  # Bootstrap + credential storage happens here
After bootstrap, the SDK stores credentials in local secure storage or environment variables and never needs the bootstrap key again.
2

Certificate-based authentication (mTLS)

For gRPC streaming connections, Synap uses mutual TLS (mTLS). Both the SDK and Synap Cloud present certificates and verify each other’s identity.The SDK’s client certificate:
  • Is issued during bootstrap by the Synap Certificate Authority
  • Has a 7-day TTL (time-to-live)
  • Is automatically renewed before expiration
  • Contains the instance identity in the certificate’s Subject Alternative Name (SAN)
Client (SDK)                    Server (Synap Cloud)
    |                                   |
    |-- ClientHello ----------------->|
    |<-- ServerHello + ServerCert ----|
    |-- ClientCert + Verify -------->|
    |<-- Finished -------------------|
    |                                   |
    |  Mutual identity verified.        |
    |  Encrypted channel established.   |
    |                                   |
3

API key authentication (REST)

For REST API calls, the SDK includes the API key as a Bearer token:
POST /v1/memories HTTP/1.1
Host: api.synap.maximem.ai
Authorization: Bearer sk_live_a1b2c3d4...
Content-Type: application/json
API keys are long-lived but can be rotated through the Dashboard or programmatically via the credential rotation API.
Synap authentication flow showing bootstrap, certificate issuance, and ongoing authentication

​
Bootstrap keys

Bootstrap keys are the entry point to Synap’s authentication system. They are designed to be used exactly once and then discarded.

​
How bootstrap keys work

  1. You generate a bootstrap key in the Synap Dashboard — navigate to your instance and open the Credentials section
  2. The Dashboard displays the raw key (e.g., bk_a1b2c3d4e5f6...). This is the only time the raw key is visible.
  3. The key is validated by Synap Cloud during bootstrap
  4. After successful bootstrap, the key is marked as consumed and cannot be reused

​
Key properties

PropertyValue
FormatOpaque token generated by Synap
UsageSingle-use — consumed after successful bootstrap
VisibilityShown once at generation time, never retrievable again
The bootstrap key is displayed only once when generated. Store it immediately in a secure location — a secrets manager, password vault, or encrypted configuration. If you lose the key before bootstrapping, you must generate a new one from the Dashboard.

​
Generating a bootstrap key

  1. Navigate to your instance in the Dashboard
  2. Go to Settings > Bootstrap Keys
  3. Click Generate Bootstrap Key
  4. Copy the displayed key and store it securely
  5. The key is now ready for use with the SDK

​
Certificate lifecycle

The SDK’s mTLS certificates follow a managed lifecycle with automatic renewal.

​
Timeline

Day 0          Day 5          Day 7          Day 9
  |              |              |              |
  v              v              v              v
Issued     Renewal Window    Expires     Grace Period Ends
           (auto-renew)                  (hard failure)
PhaseDurationWhat happens
ActiveDays 0-7Certificate is valid. All mTLS connections succeed.
Renewal windowDays 5-7SDK automatically requests a new certificate. Old cert remains valid.
Grace periodDays 7-9 (48 hours)Expired certificate is still accepted to prevent hard failures during renewal.
ExpiredAfter Day 9Certificate is rejected. SDK must re-bootstrap or use an alternative credential.
The SDK handles certificate renewal automatically. You do not need to monitor certificate expiration or manually rotate certificates. The renewal happens transparently during the renewal window (2 days before expiration).

​
Certificate validation

When the SDK connects via mTLS, Synap Cloud validates:
  1. CA signature — The certificate was issued by a trusted Synap Certificate Authority
  2. Certificate status — The certificate is active and not revoked
  3. Instance binding — The certificate is bound to the correct instance identity
  4. Expiration — The certificate is within the accepted validity window
All four checks must pass for the connection to be established.

​
API keys

API keys authenticate REST API calls. They are issued during bootstrap and remain valid until explicitly rotated or revoked.

​
Using API keys

# The SDK handles API key inclusion automatically
# You never need to manually set headers

response = await sdk.memories.create(
    document="User said they prefer dark mode",
    document_type="ai-chat-conversation",
    user_id="user_123"
)
Under the hood, the SDK sends: 
POST /v1/memories HTTP/1.1
Host: api.synap.maximem.ai
Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8...
Content-Type: application/json
X-Instance-ID: inst_a1b2c3d4e5f67890

​
Rotating API keys

You can rotate API keys through the Dashboard or programmatically. During rotation, both the old and new keys are valid for a short overlap period to prevent downtime. 
# Programmatic rotation
new_key = await sdk.credentials.rotate_api_key()
print(f"New API key issued. Old key valid for 5 more minutes.")

​
Credential sources

The SDK resolves credentials from multiple sources in order of priority:
1

Constructor arguments (highest priority)

Credentials passed directly to the SDK constructor take the highest priority:
sdk = MaximemSynapSDK(
    instance_id="inst_a1b2c3d4e5f67890",
    bootstrap_token="bk_a1b2c3d4...",
    api_key="sk_live_..."  # Optional: skip bootstrap if you have a key
)
2

Environment variables

If not provided in the constructor, the SDK checks environment variables:
export SYNAP_INSTANCE_ID="inst_a1b2c3d4e5f67890"
export SYNAP_BOOTSTRAP_TOKEN="bk_a1b2c3d4..."
export SYNAP_API_KEY="sk_live_..."
export SYNAP_CLIENT_CERT="base64-encoded-cert"
export SYNAP_CLIENT_KEY="base64-encoded-key"
3

File-based credentials (lowest priority)

The SDK checks local secure cached credentials from a previous bootstrap when constructor arguments and environment variables are not provided.

​
Authorization model

After authentication, Synap enforces authorization through the AuthContext — an immutable identity envelope that accompanies every request through the system. The AuthContext contains:
  • Instance ID — Which instance is making the request
  • Client ID — Which client (organization) owns the instance
  • Scopes — What memory scopes the request can access
  • Permissions — What operations the request can perform
Authorization is enforced at the Synap Cloud gateway, not in the SDK. Even if the SDK is compromised, it cannot escalate privileges or access memories outside its authorized scope boundaries.

​
Security best practices

Use AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or your platform’s native secrets management. Never hardcode bootstrap keys in source code or commit them to version control.
For Docker, Kubernetes, or serverless deployments, use environment-based credential storage instead of file-based. Mount secrets as environment variables from your orchestrator’s secrets management system.
While API keys don’t expire automatically, rotating them periodically (e.g., every 90 days) limits the blast radius of a potential key compromise. Use the credential rotation API or Dashboard to rotate keys with zero downtime.
The Dashboard provides an audit log of all authentication events — bootstrap attempts, certificate issuances, key rotations, and failed authentication attempts. Set up alerts for unexpected authentication patterns.
Never share bootstrap keys or credentials between environments. Create separate instances for development, staging, and production, each with their own credentials and scope boundaries.

​
Next steps

Storage Infrastructure

Configure vector and graph storage engines for your deployment.

SDK Initialization

Explore all SDK initialization options, including custom credential providers.

Clients & Instances

Understand the client and instance model that underpins authentication scopes.