General
What is the Essal API? The Essal API is a unified REST API that provides programmatic access to all six apps in the Essal suite — Office, Access, Sales, Careers, Project, and Guard. All apps share a common authentication layer, data model, and pagination format. Do I need to use all six apps? No. Each app is independent. You can use the API for only the apps you need. Apps can be enabled or disabled per workspace. Is there a free tier? The sandbox environment is free and available to all registered accounts. Production usage requires a paid workspace plan. See essal.cloud/pricing for plan details.Authentication
What authentication methods are supported? Essal supports API keys (for server-to-server integrations) and OAuth 2.0 with PKCE (for user-facing apps). See Authentication. How do I rotate an API key? API keys cannot be edited after creation. Generate a new key in Settings → Developer → API Keys, update your integration, then delete the old key. Can I use a single API key across all apps? Yes. An API key is scoped to a workspace and can carry permissions for any combination of apps. Assign only the scopes your integration actually needs.Apps & Data
How do the six apps share data? Apps share data through the Essal Core API using typed cross-app references (linked_resources). For example, a Project task can reference a Sales deal or an Office document. See Data Model.
How do I link records between apps?
Add a linked_resources array to any entity with { "type": "app.entity_type", "id": "entity_id" }. Both apps must be enabled in the workspace.
Are deleted records recoverable?
Deleted records are soft-deleted by default and retained for 30 days. To recover a soft-deleted record, update its status to active. Hard-deleted records (?hard=true) are permanent.
Webhooks
Why is my webhook endpoint receiving duplicate events? Essal delivers events with at-least-once guarantees. Retry deliveries may result in duplicates. Use the eventid field to deduplicate in your handler.
How do I test webhooks locally?
Use a tunnelling tool such as ngrok to expose your local server, then register your tunnel URL as a webhook endpoint against the sandbox environment.
Rate Limits
What happens when I hit the rate limit? The API returns429 Too Many Requests with a Retry-After header indicating how many seconds to wait. Official SDKs handle this automatically.
Can I increase my rate limits?
Enterprise plans support higher rate limits. Contact support.essal.cloud to discuss your needs.