sencho/docs/features/api-tokens.mdx

---
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 **Admiral** license. Skipper 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 lifecycle operations: deploy, down, restart, stop, start, update |
| **Full Admin** | All read and write operations except the universal restrictions listed below |

Choose the narrowest scope that fits your use case. A CI pipeline that only deploys stacks should use **Deploy Only**, not Full Admin.

### Universal restrictions

Regardless of scope, **all** API tokens are blocked from:

| Category | Description |
|----------|-------------|
| **Password management** | Changing user passwords |
| **User management** | Creating, updating, deleting, or listing user accounts |
| **SSO configuration** | Viewing, creating, updating, deleting, or testing SSO providers |
| **Node management** | Adding, updating, or deleting remote nodes |
| **License management** | Activating or deactivating license keys |
| **Token management** | Creating, listing, or revoking API tokens |
| **Registry management** | Viewing, creating, updating, deleting, or testing registry credentials |
| **Console access** | Generating console session tokens for interactive terminals |

These restrictions ensure that API tokens cannot escalate privileges or modify the identity and infrastructure configuration of your Sencho instance. These operations require a human user session (browser login).

## Creating a token

1. Open **Settings Hub** and navigate to the **API Tokens** tab (visible to Admiral admins only).
2. Click **Create Token**.
3. Fill in the creation form:
   - **Name**: A descriptive label (e.g., "GitHub Actions deploy")
   - **Permission Scope**: Select Read Only, Deploy Only, or Full Admin
   - **Expiration**: Choose 30 days, 60 days, 90 days, 1 year, or no expiration. Tokens without an expiration must be revoked manually.
4. Click **Create**. A green banner appears with the raw token value. Copy it immediately using the copy button.

<Note>
  Each user can have up to **25 active API tokens**. Token names must be unique among your active tokens. If you need to reuse a name, revoke the existing token first.
</Note>

<Frame>
  <img src="/images/api-tokens/api-tokens-overview.png" alt="API Tokens management view in Settings Hub showing the token list and create form" />
</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>

## Managing tokens

The token list displays each active token as a card showing:

- **Name** and **scope badge** (color-coded: teal for Read Only, gray for Deploy Only, red for Full Admin)
- **Created date**
- **Last used** timestamp (relative, e.g., "3h ago"), or "Never" if unused
- **Expiration date**, if one was set. Expired tokens are marked in red.

## 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. A confirmation dialog warns that revoking the token will immediately invalidate it and break any pipelines or scripts using it. After confirmation, revocation is instant: 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.
- **JWT-level expiry ceiling**: Every token includes a built-in expiry at the JWT level as defense-in-depth, independent of the user-configured expiration. The database-level expiry is always the tighter constraint.
- **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.
- **Per-user limits**: Each user can create up to 25 active tokens. Token names must be unique among active tokens for the same user.
- **Usage tracking**: Each token tracks when it was last used, visible in the token list.
- **Scope enforcement**: Permission checks happen at the middleware level before any route handler executes, ensuring consistent enforcement across all endpoints.