mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-06 08:58:05 +00:00
Anso
954994cdc0
- Fix deploy-only allowlist to match actual routes (deploy, down, restart, stop, start, update) instead of non-existent /up, /pull, /compose/* paths - Block API tokens from auth-sensitive routes (password change, node token generation) that bypass scope enforcement middleware - Add WebSocket scope enforcement: read-only/deploy-only tokens can only access logs and notifications, not host console or container exec - Prevent API token self-replication: tokens cannot create, list, or revoke other tokens regardless of scope - Map deploy-only tokens to admin role so they pass requireAdmin on deploy routes (scope middleware still restricts which endpoints they can reach) - Add optional token expiration (30, 60, 90, 365 days or no expiry) - Add token name length validation (max 100 characters) - Surface fetchTokens errors in frontend instead of swallowing silently - Fix docs: correct deploy-only scope description and GitHub Actions example
79 lines
3.2 KiB
Plaintext
79 lines
3.2 KiB
Plaintext
---
|
|
title: API Tokens
|
|
description: Generate scoped API tokens for CI/CD pipelines, scripts, and automation workflows with granular permission control.
|
|
---
|
|
|
|
<Note>
|
|
API Tokens require a Sencho **Team Pro** license. Personal Pro and Community Edition do not include this feature.
|
|
</Note>
|
|
|
|
API tokens let you authenticate external tools — CI/CD pipelines, deployment scripts, monitoring integrations — without sharing user credentials. Each token is scoped to a specific permission level so you can follow the principle of least privilege.
|
|
|
|
## Permission scopes
|
|
|
|
Every token is created with one of three permission levels:
|
|
|
|
| Scope | Allowed actions |
|
|
|-------|----------------|
|
|
| **Read Only** | `GET` requests only — view stacks, containers, metrics, and settings |
|
|
| **Deploy Only** | Everything in Read Only, plus stack operations: deploy, down, restart, stop, start, update |
|
|
| **Full Admin** | Unrestricted access — equivalent to an admin user session |
|
|
|
|
Choose the narrowest scope that fits your use case. A CI pipeline that only deploys stacks should use **Deploy Only**, not Full Admin.
|
|
|
|
## Creating a token
|
|
|
|
1. Open **Settings Hub** and navigate to the **API Tokens** tab (visible to Team Pro admins only).
|
|
2. Click **Create Token**.
|
|
3. Enter a descriptive name (e.g., "GitHub Actions deploy") and select a permission scope.
|
|
4. Click **Create**. The raw token is displayed **once** — copy it immediately.
|
|
|
|
<Frame>
|
|
<img src="/images/api-tokens/api-tokens-overview.png" alt="API Tokens management view in Settings Hub" />
|
|
</Frame>
|
|
|
|
<Warning>
|
|
The token value is shown only at creation time. Sencho stores a SHA-256 hash of the token, not the token itself. If you lose it, revoke and create a new one.
|
|
</Warning>
|
|
|
|
## Using a token
|
|
|
|
Pass the token as a Bearer token in the `Authorization` header:
|
|
|
|
<CodeGroup>
|
|
```bash curl
|
|
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
|
https://your-sencho-instance/api/stacks
|
|
```
|
|
|
|
```yaml GitHub Actions
|
|
- name: Deploy stack
|
|
run: |
|
|
curl -X POST \
|
|
-H "Authorization: Bearer ${{ secrets.SENCHO_TOKEN }}" \
|
|
https://your-sencho-instance/api/stacks/my-app/deploy
|
|
```
|
|
</CodeGroup>
|
|
|
|
### Scope enforcement
|
|
|
|
If a token attempts an action outside its scope, Sencho returns a `403` response with a `SCOPE_DENIED` error code:
|
|
|
|
```json
|
|
{
|
|
"error": "API token scope \"read-only\" only allows GET requests.",
|
|
"code": "SCOPE_DENIED"
|
|
}
|
|
```
|
|
|
|
## Revoking a token
|
|
|
|
Click the trash icon next to any token in the API Tokens settings tab. Revocation is immediate — any in-flight or future requests using the revoked token will receive a `401` response.
|
|
|
|
## Security model
|
|
|
|
- **Hashed storage** — Only a SHA-256 hash of the token is stored in the database. The raw token is never persisted.
|
|
- **Audit trail** — All actions performed via API tokens are recorded in the [Audit Log](/features/audit-log) under the creating user's username.
|
|
- **Optional expiry** — Tokens can be created with an expiration period (30 days, 60 days, 90 days, or 1 year). Tokens without an expiry must be revoked manually when no longer needed.
|
|
- **Scope enforcement** — Permission checks happen at the middleware level before any route handler executes, ensuring consistent enforcement across all endpoints.
|