Authentication

Authentication

API Keys

The Essabu SDK uses API keys for authentication. API keys are prefixed to indicate their environment:

Prefix	Environment	Description
esa_live_	Production	Live data, real transactions
esa_test_	Sandbox	Test data, safe for testing

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 will only be displayed once

Using API Keys

Direct Parameter

from essabu import Essabu

client = Essabu(api_key="esa_live_abc123", tenant_id="your-tenant")

Environment Variable

export ESSABU_API_KEY=esa_live_abc123
export ESSABU_TENANT_ID=your-tenant

client = Essabu()  # reads from environment

Managing API Keys via SDK

You can manage API keys programmatically through the Identity module:

# List all API keys
keys = client.identity.api_keys.list()

# Create a new API key
key = client.identity.api_keys.create(
    name="CI/CD Pipeline",
    scopes=["read", "write"],
)
print(key["api_key"])  # Save this -- shown only once

# Delete an API key
client.identity.api_keys.delete("key-uuid")

Multi-Tenant Access

Every request includes a tenant_id to route to the correct tenant:

# Access tenant A
client_a = Essabu(api_key="esa_live_xxx", tenant_id="tenant-a")

# Access tenant B
client_b = Essabu(api_key="esa_live_xxx", tenant_id="tenant-b")

Authentication Errors

If authentication fails, an AuthenticationError is raised:

from essabu.common.exceptions import AuthenticationError

try:
    client = Essabu(api_key="invalid-key", tenant_id="tenant")
    client.hr.employees.list()
except AuthenticationError:
    print("Invalid API key or expired token")

Security Best Practices

1. Never hardcode API keys in source code -- use environment variables or secret managers
2. Rotate keys regularly via the dashboard or API
3. Use scoped keys with minimal permissions for each service
4. Use test keys (esa_test_) in development and CI environments
5. Store keys securely in tools like AWS Secrets Manager, HashiCorp Vault, or .env files excluded from version control