kiddo/docs/_archive/admin-token-operations.md

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.