Authentication

Authentication

API Key Authentication

The Essabu SDK uses API key authentication. Every request includes your API key and tenant ID as HTTP headers:

X-API-Key: ess_live_xxxxxxxxxxxx
X-Tenant-Id: your-tenant-uuid

Obtaining an API Key

1. Log in to the Essabu Dashboard
2. Navigate to Settings > API Keys
3. Click Create API Key
4. Copy the key immediately (it is only shown once)

API Key Types

Prefix	Environment	Usage
ess_live_	Production	Live data, real transactions
ess_test_	Sandbox	Test data, no real side effects

Tenant Context

Every request is scoped to a tenant. The tenant ID determines which organization's data you access.

Essabu essabu = Essabu.builder()
    .apiKey("ess_live_xxxxxxxxxxxx")
    .tenantId("tenant-uuid")  // All requests scoped to this tenant
    .build();

User Authentication (Identity Module)

For user-facing applications, the Identity module provides authentication flows:

// Login and get tokens
Map tokens = essabu.identity().auth().login(Map.of(
    "email", "user@example.com",
    "password", "secret"
));

String accessToken = (String) tokens.get("accessToken");
String refreshToken = (String) tokens.get("refreshToken");

// Refresh an expired token
Map refreshed = essabu.identity().auth().refresh(Map.of(
    "refreshToken", refreshToken
));

// Logout
essabu.identity().auth().logout();

Two-Factor Authentication (2FA)

// Enable 2FA
Map qrCode = essabu.identity().auth().enable2FA(Map.of());
// Display qrCode.get("qrCodeUrl") to the user

// Verify 2FA code
essabu.identity().auth().verify2FA(Map.of("code", "123456"));

// Generate recovery codes
Map recovery = essabu.identity().auth().generateRecoveryCodes();

API Key Management

Manage API keys programmatically:

// List API keys
var keys = essabu.identity().apiKeys().list(PageRequest.builder().build());

// Create a new API key
Map apiKey = essabu.identity().apiKeys().create(Map.of(
    "name", "CI/CD Key",
    "scopes", List.of("read", "write")
));

// Revoke an API key
essabu.identity().apiKeys().revoke(apiKeyId);

Session Management

// List active sessions
var sessions = essabu.identity().sessions().list(PageRequest.builder().build());

// Revoke a specific session
essabu.identity().sessions().revoke(sessionId);

// Revoke all sessions
essabu.identity().sessions().revokeAll();

Security Best Practices

1. Never hardcode API keys in source code. Use environment variables or secret managers.
2. Use test keys (ess_test_) during development.
3. Rotate keys regularly and revoke unused keys.
4. Restrict scopes when creating API keys -- grant only the permissions needed.
5. Store tokens securely in user-facing applications.