> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate with the Essal API using API keys or OAuth 2.0. Understand scopes, token lifetimes, and key rotation.

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

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

### Using an API Key

Pass the key as a request header:

```bash theme={null}
curl -X GET https://api.essal.cloud/v1/office/documents \
  -H "X-API-Key: esk_live_xxxxxxxxxxxxxxxxxxxx"
```

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

## 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             |

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