Authentication

The Essal API supports two authentication methods: API Keys for server-to-server integrations, and OAuth 2.0 for user-facing flows. Both methods use the same header and share a unified scope system across all six apps.

API Keys

API keys are the fastest way to authenticate. They are long-lived credentials tied to a workspace and a set of scopes.

Creating an API Key

Go to Settings → Developer → API Keys in the admin dashboard
Click Create API Key
Assign a name and select the required scopes (e.g. office:read, sales:write)
Copy and securely store the key — it is shown only once

Using an API Key

Pass the key as a request header:

curl -X GET https://api.essal.cloud/v1/office/documents \
  -H "X-API-Key: esk_live_xxxxxxxxxxxxxxxxxxxx"

API keys grant access to your entire workspace. Store them in environment variables or a secrets manager — never hard-code them in source files.

OAuth 2.0

For applications acting on behalf of a user, use the OAuth 2.0 Authorization Code flow with PKCE.

Authorization Flow

1. Redirect user to:
   https://access.essal.cloud/oauth/authorize
     ?client_id=YOUR_CLIENT_ID
     &redirect_uri=https://app.example.com/callback
     &response_type=code
     &scope=office:read sales:read
     &code_challenge=BASE64URL(SHA256(verifier))
     &code_challenge_method=S256

2. User authenticates and approves scopes

3. Exchange the code for tokens:
   POST https://access.essal.cloud/oauth/token
   {
     "grant_type": "authorization_code",
     "code": "AUTH_CODE",
     "redirect_uri": "https://app.example.com/callback",
     "client_id": "YOUR_CLIENT_ID",
     "code_verifier": "VERIFIER"
   }

The response includes an access_token (1-hour lifetime) and a refresh_token (30-day lifetime).

Scopes Reference

Scope	Access
`office:read`	Read documents, sheets, files
`office:write`	Create and update documents, sheets, files
`access:read`	Read users, groups, sessions
`access:write`	Manage users, groups, provision/deprovision
`sales:read`	Read contacts, deals, pipelines
`sales:write`	Create and update CRM records
`careers:read`	Read jobs, applications, stages
`careers:write`	Manage job postings and applicant pipelines
`project:read`	Read projects, tasks, time entries
`project:write`	Manage tasks, assign work, log time
`guard:read`	Read policies, audit logs, alerts
`guard:write`	Manage policies and alert rules

Use the narrowest scope necessary for each integration. The read:all and write:all convenience scopes are available but not recommended for production keys.

Getting Started

Platform Concepts

App Guides — Office

App Guides — Access

App Guides — Sales

App Guides — Careers

App Guides — Project

App Guides — Guard

Integrations

Security & Compliance

API Keys

Creating an API Key

Using an API Key

OAuth 2.0

Authorization Flow

Scopes Reference

​API Keys

​Creating an API Key

​Using an API Key

​OAuth 2.0

​Authorization Flow

​Scopes Reference

API Keys

Creating an API Key

Using an API Key

OAuth 2.0

Authorization Flow

Scopes Reference