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

# Authentication

> Choose and send the right credential for automating e6data - service tokens with least-privilege permissions.

Every request carries a **token** in the `Authorization` header. Pick the credential that fits the caller.

| Credential | Best for | How to get it |
| - | - | - |
| **Service Tokens** *(recommended for apps and CI)* | Unattended apps and pipelines with their own identity and role | Create a service token from the Control Plane under Access Control |

**How to send it** - it works as a Bearer token, and is also accepted via `X-API-Key`. A Bearer token always takes precedence over a browser session cookie.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# service token usage:
curl -H "Authorization: Bearer e6sa_…" https://<HOST>/api/v1/queryservices
```

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    autonumber
    participant U as You / admin
    participant E as e6data
    participant S as Secret manager
    participant A as Your automation
    U->>E: Create a key (Console or API)
    E-->>U: Raw token - shown once
    U->>S: Store the token
    A->>S: Read token at runtime
    A->>E: Request with Authorization: Bearer token
    E-->>A: Verify token + check permission → allow or 403
```

## Permissions

Access is governed by role-based permissions on each resource. A `403` response names the permission the call needs, so you can grant least privilege.

| Resource | Actions |
| - | - |
| Clusters (`query_engine.clusters`) | `read`, `create`, `update` (covers suspend / resume / scale), `delete` |
| Catalogs (`query_engine.catalog`) | `read`, `create`, `update`, `delete`, `refresh` |
| Query history (`query_engine.history`) | `read` |
| System catalog (`query_engine.system_catalog`) | `read`, `execute` |

The built-in roles - **Admin**, **Manager**, and **Viewer** - cover common cases; create custom roles for tighter scoping. Grant a service token the **minimum** it needs.

## Security

* A raw token is **shown exactly once** - store it in a secret manager at creation.
* Use **one credential per consumer**; set an expiry and rotate before it lapses.
* Never log the secret (log the token ID instead) and never commit it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.