ID: DOC_000006 | Version: 0.2.3 | Status: Draft
Archived – superseded by new documentation.
By: Codex (GPT-5)

# Admin Token Operations

## Purpose
This document describes how operators create and manage pre-shared enrollment tokens for clients.

## Pre-Shared Token Creation
Operators generate a single-use enrollment token and share it out-of-band with the client.

Recommended properties:
- Single-use only
- Short TTL (e.g., 24h)
- Scoped to `project_id` and optional `client_id`/`software_id`

## Admin Interfaces
We provide both an Admin API and a CLI tool for token operations. A frontend will be added later.

### Admin User and Access
- An admin user must exist to operate token workflows.
- Initial access uses a local admin token.
- Later, admin auth will be integrated with the OIDC service.

### CLI and Admin API Capabilities
- Create enrollment tokens
- List token metadata (no plaintext output)
- Revoke tokens
- Export a token as a file for client installation

### Local Admin Token (Initial Phase)
- Admin requests must include `Authorization: Bearer <ADMIN_TOKEN>`.
- The admin token is stored locally (e.g., `.env`) and never committed.

Example `.env` (local only):
```
ADMIN_TOKEN=change-me-please
```

Minimal flow (first token):
1) Set `ADMIN_TOKEN` in `.env`.
2) Call `POST /v1/admin/enrollment-tokens` with the bearer token.
3) Export the returned one-time token to a file and hand it to the client.

## Admin API (Draft)
All admin endpoints are authenticated. Initial auth is local; later OIDC.

Base path:
- `/v1/admin`

Endpoints:
- `POST /v1/admin/enrollment-tokens`
  - Create a pre-shared enrollment token.
  - Request: `project_id`, optional `client_id`, optional `software_id`, optional `expires_at`.
  - Response: token metadata + one-time plaintext token.
- `GET /v1/admin/enrollment-tokens`
  - List token metadata (never return plaintext tokens).
  - Supports filtering by `project_id`, `client_id`, `status` (active/used/expired).
- `POST /v1/admin/enrollment-tokens/{token_id}/revoke`
  - Revoke a token (marks as revoked or sets `used_at`/`revoked_at`).
- `GET /v1/admin/enrollment-tokens/{token_id}/export`
  - Export the one-time token to a file download (single use).

## CLI (Draft)
Example commands (names can be adjusted):
- `update-service admin token create --project <id> [--client <id>] [--software <id>] [--expires <iso8601>]`
- `update-service admin token list --project <id> [--status active|used|expired|revoked]`
- `update-service admin token revoke --id <token_id>`
- `update-service admin token export --id <token_id> --out ./enroll-token.txt`

Example format:
```
enroll_<random_32_bytes>
```

## Storage and Safety
- Store only a hash of the enrollment token (never plaintext).
- Track `created_at`, `expires_at`, and `used_at`.
- Deny enrollment if `expires_at` is exceeded or `used_at` is set.

## Rotation and Revocation
- Revoke enrollment tokens by invalidating their stored hash.
- Issue a new enrollment token if the previous one expires or is leaked.

## Distribution
Preferred channels:
- One-time install code (copy/paste)
- QR code
- Encrypted file included in an install bundle

## Audit Expectations
- Log token creation and enrollment usage for traceability.