Authentication

Jo uses secure authentication methods to protect your store data while providing seamless access to analytics. This guide covers how authentication works and how to manage access.

Overview

Jo implements OAuth 2.0 for store connections and JWT tokens for API access, ensuring:

  • Secure data transmission
  • Granular permission control
  • Token-based session management
  • Multi-factor authentication support

Store Authentication

OAuth 2.0 Flow

When connecting your e-commerce platform, Jo uses OAuth 2.0:

  1. Authorization Request: Jo redirects you to your platform's auth page
  2. User Consent: You approve the requested permissions
  3. Authorization Code: Platform sends a temporary code to Jo
  4. Token Exchange: Jo exchanges the code for access tokens
  5. Secure Storage: Tokens are encrypted and stored securely
// Example OAuth flow for Shopify
const authUrl = `https://mystore.myshopify.com/admin/oauth/authorize?
  client_id=${JO_CLIENT_ID}&
  scope=read_products,read_orders,read_customers&
  redirect_uri=${JO_REDIRECT_URI}&
  state=${CSRF_TOKEN}`;

Permissions Required

Jo requests only the minimum permissions needed:

Shopify

  • read_products: Product catalog and inventory
  • read_orders: Order history and analytics
  • read_customers: Customer data and segments
  • read_reports: Sales and analytics reports

WooCommerce

  • read: Access to orders, products, and customers
  • reports: Analytics and reporting data

API Authentication

Getting Your API Key

  1. Log in to your Jo dashboard
  2. Navigate to Settings > API Access
  3. Click "Generate API Key"
  4. Copy and securely store your key

Using Your API Key

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.getjo.io/v1/analytics/sales

API Key Best Practices

  • Never share your API key publicly
  • Rotate keys every 90 days
  • Use environment variables in your code
  • Restrict by IP for production environments
// Good: Using environment variables
const apiKey = process.env.JO_API_KEY;

// Bad: Hardcoding keys
const apiKey = "jo_live_abc123..."; // Never do this!

User Authentication

Login Methods

Jo supports multiple authentication methods:

  1. Email/Password: Traditional login with strong password requirements
  2. SSO: Single Sign-On via Google, Microsoft, or Okta
  3. Magic Links: Passwordless email authentication
  4. Two-Factor Auth: Additional security with TOTP

Setting Up 2FA

  1. Go to Account Settings > Security
  2. Click "Enable Two-Factor Authentication"
  3. Scan the QR code with your authenticator app
  4. Enter the verification code
  5. Save your backup codes securely

Team Access Management

Role-Based Access Control

Jo implements RBAC with predefined roles:

RolePermissions
OwnerFull access, billing, team management
AdminAll analytics, settings, no billing
AnalystView analytics, create reports
ViewerRead-only access to dashboards

Inviting Team Members

POST /api/v1/team/invite
{
  "email": "teammate@company.com",
  "role": "analyst",
  "dashboards": ["sales", "inventory"]
}

Custom Permissions

Enterprise plans can create custom roles:

{
  "role_name": "Marketing Manager",
  "permissions": {
    "analytics": ["read"],
    "dashboards": ["read", "write"],
    "reports": ["read", "write", "export"],
    "settings": ["read"]
  }
}

Security Features

Session Management

  • Sessions expire after 24 hours of inactivity
  • Concurrent session limits based on plan
  • Session history available in security settings
  • Remote session termination

IP Whitelisting

For additional security, restrict access by IP:

  1. Navigate to Settings > Security
  2. Enable "IP Whitelisting"
  3. Add allowed IP addresses or ranges
  4. Save and test access

Audit Logs

Track all authentication events:

{
  "event": "login",
  "user": "user@example.com",
  "ip": "192.168.1.1",
  "timestamp": "2024-01-15T10:30:00Z",
  "device": "Chrome/MacOS",
  "status": "success"
}

Token Management

Access Token Lifecycle

  • Duration: 1 hour for access tokens
  • Refresh: 30 days for refresh tokens
  • Rotation: Automatic token refresh
  • Revocation: Immediate invalidation available

Refreshing Tokens

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://api.getjo.io/v1/auth/refresh', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ refresh_token: refreshToken }),
  });
  
  const { access_token, expires_in } = await response.json();
  return { access_token, expires_in };
}

Webhooks Authentication

Secure your webhooks with signature verification:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return hash === signature;
}

Troubleshooting

Common Issues

Invalid Token Error

  • Check token expiration
  • Verify correct environment (staging vs production)
  • Ensure proper header format

Permission Denied

  • Verify user role has required permissions
  • Check if specific features are plan-restricted
  • Confirm store connection permissions

Too Many Login Attempts

  • Wait 15 minutes before trying again
  • Use password reset if needed
  • Contact support for immediate unlock

Best Practices

  1. Use Strong Passwords: Minimum 12 characters with mixed case, numbers, and symbols
  2. Enable 2FA: Adds crucial second layer of security
  3. Regular Audits: Review team access quarterly
  4. API Key Rotation: Change keys every 90 days
  5. Monitor Access: Check audit logs for unusual activity

Next Steps