Authentication

How to authenticate with the OnboardSync API

Overview

The OnboardSync API uses different authentication methods depending on the use case:

• Secret Keys: For mobile SDKs to fetch onboarding configurations
• JWT Tokens: For dashboard users and management operations
• API Keys: For server-to-server integrations

Mobile SDK Authentication

Mobile SDKs use project-specific secret keys that are safe to include in mobile apps:

// Flutter
await OnboardSync.showOnboarding(
  context,
  projectId: 'your-project-id',
  secretKey: 'your-secret-key'
);

// React Native
<OnboardSyncComponent
  projectId="your-project-id"
  secretKey="your-secret-key"
/>

// Swift
let config = OnboardSyncConfig(
  projectId: "your-project-id",
  secretKey: "your-secret-key"
)

Secret keys are included in request headers:

X-Project-Id: your-project-id
X-Secret-Key: your-secret-key

Secret keys only allow read access to onboarding configurations and posting analytics events. They cannot modify your project settings.

Dashboard Authentication

The dashboard uses Supabase authentication with JWT tokens:

Authorization: Bearer YOUR_JWT_TOKEN

This is handled automatically when you log in to the dashboard. The JWT token is included in all API requests made from the dashboard.

API Key Authentication

For server-to-server integrations and custom tools, use your personal API key:

curl -X GET https://onboardsync.vercel.app/api/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Obtaining Your API Key

1. Log in to the OnboardSync Dashboard
2. Click on your profile icon
3. Select “API Keys”
4. Your API key will be displayed (it’s automatically generated for your account)

Your API key provides full access to all your projects. Keep it secure and never expose it in client-side code.

Request Examples

Mobile SDK Request

# Fetching onboarding configuration
POST https://onboardsync.vercel.app/api/onboarding/resolve
X-Project-Id: your-project-id
X-Secret-Key: your-secret-key
Content-Type: application/json

{
  "deviceId": "unique-device-id"
}

Dashboard/API Key Request

# Creating a new flow
POST https://onboardsync.vercel.app/api/flows
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "projectId": "your-project-id",
  "name": "New User Onboarding",
  "status": "active"
}

JavaScript/Node.js Examples

// Mobile SDK request
const response = await fetch('https://onboardsync.vercel.app/api/onboarding/resolve', {
  method: 'POST',
  headers: {
    'X-Project-Id': 'your-project-id',
    'X-Secret-Key': 'your-secret-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ deviceId: 'unique-device-id' })
});

// Management API request
const response = await fetch('https://onboardsync.vercel.app/api/flows', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

Python Examples

import requests

# Mobile SDK request
headers = {
    'X-Project-Id': 'your-project-id',
    'X-Secret-Key': 'your-secret-key',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://onboardsync.vercel.app/api/onboarding/resolve',
    headers=headers,
    json={'deviceId': 'unique-device-id'}
)

# Management API request
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://onboardsync.vercel.app/api/flows',
    headers=headers
)

Security Best Practices

Secret Key Usage

DO:

• Include secret keys only in mobile app code
• Use different projects for development and production
• Rotate secret keys if compromised

DON’T:

• Use secret keys for server-side operations
• Share secret keys publicly (they’re designed for client-side use)

API Key Security

API keys provide full access to your account. Never expose them in client-side code or public repositories.

DO:

• Store API keys in environment variables
• Use them only for server-side operations
• Keep them out of version control

DON’T:

• Include API keys in mobile or web apps
• Commit them to Git repositories
• Share them via insecure channels

Environment Variables

# .env file (add to .gitignore)
ONBOARDSYNC_API_KEY=your-api-key

# Usage in Node.js
const apiKey = process.env.ONBOARDSYNC_API_KEY;

Error Responses

Invalid Secret Key

{
  "error": "Invalid project credentials"
}

Invalid API Key

{
  "error": "Invalid API key",
  "status": 401
}

Missing Authentication

{
  "error": "Authentication required",
  "status": 401
}

Insufficient Permissions

{
  "error": "Insufficient permissions for this operation",
  "status": 403
}

Rate Limiting

Different authentication methods have different rate limits:

Method	Limit	Window
Secret Keys	1000 requests	Per hour
API Keys	5000 requests	Per hour
Unauthenticated	60 requests	Per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Testing

For development and testing:

1. Create a separate test project in the dashboard
2. Use the test project’s credentials in your development environment
3. This keeps test data separate from production

Next Steps

API Overview

Back to API overview

Projects API

Start using the API