gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-07-26 11:49:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(api-tokens): deep rewrite for v1, expand to fleet automation guide (#1140)

Browse Source 
Rewrite docs/features/api-tokens.mdx (115 → 442 lines) as a full
product + technical guide: mental model, scope ladder, prerequisites,
step-by-step usage with HTTP/WS/multi-node examples, complete universal-
restriction table, cross-node proxy behaviour, lifecycle, rate-limit
ceiling, security model, limitations, three example workflows,
troubleshooting accordion, FAQ accordion.

Replace the single populated-list screenshot with five captured against
production: empty state, create form, reveal banner (token value
redacted), populated list with all three scope variants, revoke modal.

Sibling-doc edits keep tier statements coherent now that API tokens are
available on every tier:
- docs/api-reference/overview.mdx: drop the Admiral-only Note callout,
  drop API Tokens from the Admiral-gated license-tier table, correct
  the rate-limit table to say tokens are keyed per-credential
- docs/features/overview.mdx: drop the "Admiral only." sentence
- docs/security.mdx: drop "Admiral tier.", move API tokens row to every
  tier in the security matrix, repoint image to the new populated shot
This commit is contained in:
Anso
2026-05-21 21:20:59 -04:00
committed by GitHub
parent dc8a368785
commit be22e3ded1
10 changed files with 398 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-reference/overview.mdx
+4 -8
View File
@@ -24,10 +24,6 @@ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
API tokens are 56-character opaque strings that begin with `sen_sk_`, for example `sen_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. The prefix makes them easy to identify in logs and is recognized by secret-scanning tools (GitHub, TruffleHog, GitGuardian).
<Note>
API Tokens require a Sencho **Admiral** license. Community and Skipper editions do not include this feature.
</Note>
### Token scopes
Every token is created with one of three permission levels:
@@ -94,12 +90,12 @@ Sencho uses a tiered rate limiting system that balances security with usability:
| Tier | Limit | Applies to | Keyed by |
|------|-------|------------|----------|
| **Polling** | 300/min | Dashboard status endpoints (`/stats`, `/system/stats`, `/stacks/statuses`, etc.) | User session |
| **Standard** | 200/min | All other API endpoints | User session |
| **Polling** | 300/min | Dashboard status endpoints (`/stats`, `/system/stats`, `/stacks/statuses`, etc.) | User session or API token |
| **Standard** | 200/min | All other API endpoints | User session or API token |
| **Webhooks** | 500/min | `POST /webhooks/:id/trigger` | IP address |
| **Auth** | 5-10/15min | Login, setup, SSO endpoints | IP address |
Authenticated requests (browser sessions and API tokens) are rate-limited per user, not per IP. This prevents teams behind shared NAT or VPN from pooling rate limit budgets. Unauthenticated requests fall back to IP-based limiting.
Authenticated requests are rate-limited per credential (per user session, or per API token). This prevents teams behind shared NAT or VPN from pooling rate limit budgets, and lets two API-token-driven automations under the same account run on independent budgets. Unauthenticated requests fall back to IP-based limiting.
Internal node-to-node traffic (requests authenticated with node proxy tokens) bypasses rate limiting entirely.
@@ -122,7 +118,7 @@ Some endpoints are gated by license tier:
| Tier | Gated features |
|------|---------------|
| **Skipper+** | Webhooks, Fleet snapshots, Stack rollback |
| **Admiral** | API Tokens, Scheduled Tasks |
| **Admiral** | Scheduled Tasks |
Requests to gated endpoints on a lower tier return `403` with the appropriate error code.