Context Switching API

Overview

Every API request in EventZR operates within a context defined by three headers:x-tenant-id,x-actor-id, andx-team-id. These headers determine which tenant's data is accessed, which user is performing the action, and which team scope applies to the operation.

Required Headers

Switching Context

Include the context headers in every API request. The JWT token already contains tenantId and userId claims, but explicit headers allow context overriding for admin operations.

const response = await fetch('/api/svc/event/v1/events', {
  headers: {
    'Authorization': 'Bearer <jwt-token>',
    'x-tenant-id': 'tenant-uuid',
    'x-actor-id': 'user-uuid',
    'x-team-id': 'team-uuid', // optional
    'Content-Type': 'application/json',
  },
});

Frontend Context Hook

Use the useContextSwitcher hook from @eventzr/react-hooks to manage context switching in React applications.

import { useContextSwitcher } from '@eventzr/react-hooks';

function MyComponent() {
  const { currentTenant, currentTeam, switchTenant, switchTeam } = useContextSwitcher();

  return (
    <div>
      <p>Tenant: {currentTenant.name}</p>
      <p>Team: {currentTeam?.name ?? 'No team'}</p>
      <button onClick={() => switchTeam('new-team-id')}>
        Switch Team
      </button>
    </div>
  );
}

Best Practices

• Always include x-tenant-id in every API call.
• Never cache data across different tenant contexts.
• Use team context for operations that should be scoped to a team wallet or quota.
• Validate context headers server-side with the JwtAuthGuard from @eventzr/auth.
• Log context switches for audit trail purposes.