Core Auth
Core Authentication
Advanced authentication patterns and security configurations with the OMX Core SDK.
Advanced Authentication
Beyond basic API key authentication, the OMX Core SDK provides advanced authentication patterns, security configurations, and credential management for enterprise applications.
JWT Token Management
For enhanced security, use JWT tokens for authentication:
typescript
1import { OMXClient } from '@omx-sdk/core';
2
3const omx = new OMXClient({
4 clientId: 'your_client_id',
5 secretKey: 'your_secret_key',
6
7 // JWT configuration
8 jwt: {
9 enabled: true,
10 algorithm: 'HS256',
11 expiresIn: '1h',
12 issuer: 'your-app',
13 audience: 'omx-api'
14 }
15});
16
17// Authenticate and get JWT token
18const token = await omx.auth.authenticate();
19console.log('JWT Token:', token);
OAuth 2.0 Integration
Integrate with OAuth 2.0 providers for user authentication:
typescript
1// OAuth configuration
2const omx = new OMXClient({
3 clientId: 'your_client_id',
4 secretKey: 'your_secret_key',
5
6 oauth: {
7 provider: 'google', // 'google', 'github', 'auth0'
8 clientId: 'oauth_client_id',
9 clientSecret: 'oauth_client_secret',
10 redirectUri: 'https://yourapp.com/callback',
11 scopes: ['openid', 'profile', 'email']
12 }
13});
14
15// Initialize OAuth flow
16const authUrl = await omx.auth.getAuthorizationUrl();
17window.location.href = authUrl;
18
19// Handle callback
20const tokens = await omx.auth.handleCallback(authCode);
Multi-Tenant Authentication
Support multiple tenants with isolated authentication:
typescript
1const omx = new OMXClient({
2 clientId: 'your_client_id',
3 secretKey: 'your_secret_key',
4
5 // Multi-tenant configuration
6 tenant: {
7 id: 'tenant_123',
8 isolationLevel: 'strict', // 'strict' or 'shared'
9 customDomain: 'tenant123.omx.com'
10 }
11});
12
13// Switch tenant context
14await omx.auth.switchTenant('tenant_456');
Role-Based Access Control (RBAC)
Implement fine-grained permissions with RBAC:
typescript
1// Define roles and permissions
2const permissions = await omx.auth.getUserPermissions();
3
4// Check permissions before API calls
5if (permissions.includes('geotrigger:create')) {
6 await omx.geotrigger.create(triggerData);
7} else {
8 throw new Error('Insufficient permissions');
9}
10
11// Role-based API calls
12const canManageCampaigns = await omx.auth.hasRole('campaign_manager');
13if (canManageCampaigns) {
14 await omx.campaign.update(campaignId, updates);
15}
Session Management
Advanced session handling and automatic token refresh:
typescript
1const omx = new OMXClient({
2 clientId: 'your_client_id',
3 secretKey: 'your_secret_key',
4
5 session: {
6 autoRefresh: true,
7 refreshThreshold: 300, // Refresh 5 minutes before expiry
8 maxRetries: 3,
9 storage: 'localStorage', // 'localStorage', 'sessionStorage', 'memory'
10
11 // Session events
12 onRefresh: (newToken) => {
13 console.log('Token refreshed:', newToken);
14 },
15 onExpire: () => {
16 console.log('Session expired, redirecting to login');
17 window.location.href = '/login';
18 }
19 }
20});
Security Headers
Configure security headers for API requests:
typescript
1const omx = new OMXClient({
2 clientId: 'your_client_id',
3 secretKey: 'your_secret_key',
4
5 security: {
6 // Custom headers
7 headers: {
8 'X-Request-ID': () => generateRequestId(),
9 'X-Client-Version': '1.0.0',
10 'X-User-Agent': 'MyApp/1.0'
11 },
12
13 // Request signing
14 signRequests: true,
15 signatureAlgorithm: 'HMAC-SHA256',
16
17 // Rate limiting
18 rateLimit: {
19 enabled: true,
20 maxRequests: 100,
21 windowMs: 60000 // 1 minute
22 }
23 }
24});
Error Handling
Handle authentication errors gracefully:
typescript
1try {
2 await omx.auth.authenticate();
3} catch (error) {
4 switch (error.code) {
5 case 'INVALID_CREDENTIALS':
6 // Handle invalid credentials
7 redirectToLogin();
8 break;
9 case 'TOKEN_EXPIRED':
10 // Attempt token refresh
11 await omx.auth.refreshToken();
12 break;
13 case 'INSUFFICIENT_PERMISSIONS':
14 // Handle permission denied
15 showErrorMessage('Access denied');
16 break;
17 case 'RATE_LIMITED':
18 // Handle rate limiting
19 await delay(error.retryAfter * 1000);
20 break;
21 default:
22 console.error('Authentication error:', error);
23 }
24}
Best Practices
- Secure Storage: Never store credentials in local storage or cookies
- Token Rotation: Implement automatic token rotation
- Permission Checks: Always validate permissions before sensitive operations
- Audit Logging: Log all authentication and authorization events
- Multi-Factor Auth: Implement MFA for sensitive operations
- Session Timeout: Set appropriate session timeouts