Skip to main content

​
Authentication

The SeamlessOS API uses a dual authentication system combining API keys for service-to-service trust and optional user tokens for permission-scoped operations. This approach ensures security while enabling flexible integration patterns.

​
Quick start

Every API request requires an API key in the X-API-Key header. For user-specific operations, also include a JWT token in the Authorization header. 
// API key only (full permissions)
const response = await fetch('https://connect.telnesstech.com/api/v2/customers', {
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY
  }
});

// API key + user token (user's permissions only)
const userResponse = await fetch('https://connect.telnesstech.com/api/v2/customers', {
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Authorization': `Bearer ${userToken}`
  }
});

​
API keys

API keys establish trust between your application and the SeamlessOS API. They grant full access to all resources within your organization’s scope.

​
Security model

API keys provide complete system access - treat them like root passwords:
  • Never expose in frontend code - API keys belong only on your secure backend servers
  • Rotate regularly - Generate new keys monthly or after any security incident
  • Environment separation - Use different keys for development, staging, and production
  • Secure storage - Store keys in environment variables or secure credential management systems

​
Getting an API key

Create and manage API keys through the SeamlessOS portal. Each key is associated with your organization and provides access to all resources you have permission to manage.

​
Usage

Include your API key in every request using the X-API-Key header: 
const response = await fetch('/api/v2/subscriptions', {
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Content-Type': 'application/json'
  }
});

​
User authentication

User tokens enable operations on behalf of specific users, automatically limiting permissions to what that user is authorized to access.

​
JWT bearer tokens

User authentication uses JWT tokens passed in the Authorization header with the Bearer scheme: 
// Include user token in Authorization header
const response = await fetch('/api/v2/subscriptions', {
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Authorization': `Bearer ${userToken}`
  }
});

​
Permission scoping

When both API key and user token are provided:
  1. API key authenticates your application’s right to use the API
  2. User token identifies the specific user and their permissions
  3. Effective permissions are limited to the intersection of both
This means even though your API key has full access, operations are restricted to what the authenticated user can actually do. Example scenarios:
  • Admin user token: Can access all customers and subscriptions
  • Limited user token: Can only access their assigned customer accounts
  • Support user token: Can view but not modify subscription details

​
Integration patterns

Backend integration: Use API key only for system-level operations like bulk processing, reporting, or administrative tasks. User-facing operations: Include user tokens when performing actions triggered by specific users in your application. 
// System operation - API key only
const allSubscriptions = await fetch('/api/v2/subscriptions', {
  headers: { 'X-API-Key': apiKey }
});

// User operation - API key + user token
const userSubscriptions = await fetch('/api/v2/subscriptions', {
  headers: {
    'X-API-Key': apiKey,
    'Authorization': `Bearer ${userToken}`
  }
});

​
Security best practices

​
API key management

  • Server-side only: Never include API keys in client-side JavaScript or mobile apps
  • Environment variables: Store keys in CONNECT_API_KEY environment variable
  • Key rotation: Update keys regularly and immediately after any suspected compromise
  • Monitoring: Track API key usage to detect unusual patterns

​
Token handling

  • Secure transmission: Always use HTTPS for API requests
  • Token expiration: Implement proper token refresh mechanisms
  • Minimal scope: Request only the permissions your application needs

​
Request security

// ✅ Good - Secure backend request
const response = await fetch('/api/v2/orders', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY,    // From secure environment
    'Authorization': `Bearer ${validUserToken}`,  // From authenticated session
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(orderData)
});

// ❌ Bad - Never expose API keys client-side
const response = await fetch('/api/v2/orders', {
  headers: {
    'X-API-Key': 'api_123abc456def',  // Exposed in browser!
  }
});

​
Troubleshooting

403 Forbidden: Check that your API key is valid and properly formatted in the X-API-Key header. 401 Unauthorized: User token may be expired, invalid, or missing required permissions for the requested operation. Missing permissions: When using user tokens, verify the user has the necessary permissions for the requested action. The API enforces the most restrictive permissions between your API key capabilities and the user’s assigned permissions.
⌘I