Authentication

Learn how to authenticate your SDK requests.

Need an API key? Deploy Synap or sign up for Synap Cloud to get your API key.

API Keys

Synap SDK uses API keys for authentication. You can get your API key from the Synap dashboard.

Environment Variables

The recommended way to store your API key is in environment variables:

.env.local


SYNAP_URL=https://api.synap.app
SYNAP_API_KEY=sk_your_api_key_here

Then use it in your code:


import { SynapSDK } from '@synap/sdk'
 
const synap = new SynapSDK({
  url: process.env.SYNAP_URL!,
  apiKey: process.env.SYNAP_API_KEY!
})

Direct Configuration

For testing, you can pass the API key directly:


const synap = new SynapSDK({
  url: 'https://api.synap.app',
  apiKey: 'sk_your_api_key_here'
})

⚠️ Warning: Never commit API keys to version control!

Dynamic Authentication

For scenarios where the auth token changes (e.g., user login/logout), use the headers function:


import { SynapSDK } from '@synap/sdk'
 
let currentToken: string | null = null
 
const synap = new SynapSDK({
  url: 'https://api.synap.app',
  headers: () => ({
    Authorization: `Bearer ${currentToken}`
  })
})
 
// Later, update the token
function login(token: string) {
  currentToken = token
}
 
function logout() {
  currentToken = null
}

Custom Authentication

If you need custom auth logic:


async function getAuthToken(): Promise<string> {
  // Your custom logic here
  const response = await fetch('/api/auth')
  const { token } = await response.json()
  return token
}
 
const synap = new SynapSDK({
  url: 'https://api.synap.app',
  headers: async () => ({
    Authorization: `Bearer ${await getAuthToken()}`
  })
})

Local Development

For local development without authentication:


const synap = new SynapSDK({
  url: 'http://localhost:3000',
  // No apiKey needed for local dev (if configured)
})

Troubleshooting

Unauthorized Errors

If you see 401 Unauthorized errors:

Check API key is valid
```
echo $SYNAP_API_KEY
```
Check URL is correct
```
echo $SYNAP_URL
```

Check environment variables are loaded


console.log('URL:', process.env.SYNAP_URL)
console.log('API Key exists:', !!process.env.SYNAP_API_KEY)

Rate Limiting

API keys have rate limits. If you hit limits:

Implement exponential backoff
Cache responses where possible
Contact support for higher limits

Security Best Practices

✅ Store API keys in environment variables
✅ Use different keys for dev/staging/production
✅ Rotate keys regularly
✅ Never expose keys in client-side code
✅ Use server-side API routes in web apps

❌ Don’t:

Commit keys to git
Share keys publicly
Use production keys in development
Log API keys

Next Steps

Quick Start → - Create your first entity
Core Concepts → - Understand event sourcing
Deploy Synap → - Set up your own instance