Skip to main content

Authentication

The Authentication module (sdk.auth) handles user registration, login, password management, and session control.

Registration​

Register a new user account:

const user = await sdk.auth.register({
  email: '[email protected]',
  name: 'John Doe',
  password: 'securepassword123',
});

console.log('User registered:', user.id);

User Verification​

After registration, users need to verify their email:

const authResult = await sdk.auth.verifyUser('verification-token-from-email');

// The SDK automatically sets the access token
console.log('Authenticated user:', authResult.user);
console.log('Available workspaces:', authResult.workspacesAndTenants);

Password Management​

Forgot Password​

Request a password reset:

const result = await sdk.auth.forgotPassword('[email protected]');
console.log('Reset email sent:', result.success);

Reset Password​

Reset password with token from email:

const result = await sdk.auth.resetPassword('newpassword123', 'reset-token');
console.log('Password reset:', result.success);

Change Password​

Change password for authenticated user:

const updatedUser = await sdk.auth.changePassword('user-id', 'newpassword123');
console.log('Password changed for:', updatedUser.email);

Session Management​

Switch Workspace​

Switch the active workspace context:

const result = await sdk.auth.switchWorkspace('workspace-id');
console.log('Switched to workspace:', result);

Switch Project​

Switch the active project context:

const result = await sdk.auth.switchProject('project-id');
console.log('Switched to project:', result);

Logout​

Clear authentication tokens:

sdk.auth.logout();
// or
sdk.clearTokens();

Token Management​

The SDK automatically manages authentication tokens, but you can also handle them manually:

// Set tokens manually
sdk.setTokens('access-token', 'refresh-token');

// Get current tokens
const tokens = sdk.getTokens();
if (tokens) {
  console.log('Access token:', tokens.accessToken);
  console.log('Refresh token:', tokens.refreshToken);
}

// Clear tokens
sdk.clearTokens();

Authentication States​

Check if user is authenticated:

const isAuthenticated = !!sdk.getTokens();

if (isAuthenticated) {
  // User is logged in
  const workspaces = await sdk.workspaces.getWorkspaces();
} else {
  // Redirect to login
  console.log('Please log in');
}

Error Handling​

Handle authentication errors:

try {
  const user = await sdk.auth.register({
    email: '[email protected]',
    name: 'John Doe',
    password: 'password123',
  });
} catch (error) {
  if (error.message.includes('already exists')) {
    console.error('Email already registered');
  } else {
    console.error('Registration failed:', error.message);
  }
}

Security Best Practices​

  1. Store tokens securely: Use secure storage for access/refresh tokens
  2. Handle token expiration: Implement token refresh logic
  3. Validate on server: Always validate tokens on the server side
  4. Use HTTPS: Only use the SDK over secure connections
  5. Clear tokens on logout: Always clear tokens when user logs out
// Example secure token storage (browser)
class TokenStorage {
  static setTokens(accessToken: string, refreshToken: string) {
    localStorage.setItem('accessToken', accessToken);
    localStorage.setItem('refreshToken', refreshToken);
  }

  static getTokens() {
    const accessToken = localStorage.getItem('accessToken');
    const refreshToken = localStorage.getItem('refreshToken');
    return accessToken && refreshToken ? { accessToken, refreshToken } : null;
  }

  static clearTokens() {
    localStorage.removeItem('accessToken');
    localStorage.removeItem('refreshToken');
  }
}

// Initialize SDK with stored tokens
const tokens = TokenStorage.getTokens();
const sdk = new WorkspacesSDK({
  endpoint: 'https://api.example.com/graphql',
  accessToken: tokens?.accessToken,
  refreshToken: tokens?.refreshToken,
});