diff --git a/docs/authentication.md b/docs/authentication.md index b94caed..1503397 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -86,6 +86,76 @@ uv run agent-memory token remove abc12345 # Remove a token without confirmation uv run agent-memory token remove abc12345 --force ``` +### CI/Terraform token bootstrapping + +You can use the token CLI to bootstrap authentication tokens in CI pipelines and infrastructure-as-code tools like Terraform. + +The key features that make this work well are: + +- `--format json` on token commands (`add`, `list`, `show`) for machine-readable output +- `--token` on `token add` to register a pre-generated secret from your CI or secrets manager + +#### GitHub Actions example (generate token in CI) + +The example below generates a short-lived token during a workflow run and exposes it via `GITHUB_ENV` for later steps: + +```yaml +- name: Create agent-memory token for CI + run: | + TOKEN_JSON=$(agent-memory token add \ + --description "CI bootstrap token" \ + --expires-days 30 \ + --format json) + echo "AGENT_MEMORY_TOKEN=$(echo "$TOKEN_JSON" | jq -r '.token')" >> "$GITHUB_ENV" +``` + +Later steps can use `AGENT_MEMORY_TOKEN` as the bearer token when calling the API. +**JSON output format for `token add`** + +When you use `--format json`, `agent-memory token add` returns a JSON object with fields like: + +```json +{ + "token": "the-plaintext-token", + "hash": "abc12345def67890...", + "description": "CI bootstrap token", + "created_at": "2025-07-10T18:30:00.000000+00:00", + "expires_at": "2025-08-09T18:30:00.000000+00:00" +} +``` + +You can extract any of these fields in your scripts (for example, `.token` or `.hash` with `jq`). + +#### Terraform example (register a pre-generated token) + +If you generate tokens outside Redis Agent Memory Server (for example via a secrets manager), you can register them using `--token` so the server only ever stores a hash: + +```hcl +variable "agent_memory_token" { + type = string + sensitive = true +} + +resource "terraform_data" "agent_memory_token" { + provisioner "local-exec" { + environment = { + AGENT_MEMORY_TOKEN = var.agent_memory_token + } + + command = < agent-memory-token.json + EOT + } +} +``` + +For Terraform versions earlier than 1.4, you can use a `null_resource` instead of `terraform_data`. + +In both cases, store the plaintext token in a secure secret store (GitHub Actions secrets, Terraform variables, Vault, etc.). The server will hash it before storing. When the CLI generates a token (without `--token`), it displays the plaintext only once; when using `--token` with a pre-generated value, ensure you've already stored it securely. **Security Features:** - Tokens are hashed using bcrypt before storage diff --git a/docs/cli.md b/docs/cli.md index 4d5984b..0d2218e 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -134,13 +134,15 @@ Manages authentication tokens for token-based authentication. The token command Creates a new authentication token. ```bash -agent-memory token add --description "DESCRIPTION" [--expires-days DAYS] +agent-memory token add --description "DESCRIPTION" [--expires-days DAYS] [--format text|json] [--token TOKEN_VALUE] ``` **Options:** - `--description TEXT` / `-d TEXT`: **Required**. Description for the token (e.g., "API access for service X") - `--expires-days INTEGER` / `-e INTEGER`: **Optional**. Number of days until token expires. If not specified, token never expires. +- `--format [text|json]`: **Optional**. Output format. `text` (default) is human-readable; `json` is machine-readable and recommended for CI or scripting. +- `--token TEXT`: **Optional**. Use a pre-generated token value instead of having the CLI generate one. The CLI will hash and store the provided token; make sure you've stored the plaintext securely in your secrets manager or CI system. **Examples:** @@ -150,6 +152,12 @@ agent-memory token add --description "API access token" --expires-days 30 # Create a permanent token (no expiration) agent-memory token add --description "Service account token" + +# Create a token and return JSON (for CI/scripts) +agent-memory token add --description "CI token" --expires-days 30 --format json + +# Register a pre-generated token (e.g., from a secrets manager) +agent-memory token add --description "Terraform bootstrap" --token "$MY_TOKEN" --format json ``` **Security Note:** The generated token is displayed only once. Store it securely as it cannot be retrieved again. @@ -159,7 +167,28 @@ agent-memory token add --description "Service account token" Lists all authentication tokens, showing masked token hashes, descriptions, and expiration dates. ```bash -agent-memory token list +agent-memory token list [--format text|json] +``` + +When `--format json` is used, the command prints a JSON array of token summaries suitable for scripting and CI pipelines. The default `text` format produces human-readable output like the example below. +**JSON Output Example:** +```json +[ + { + "hash": "abc12345def67890xyz", + "description": "API access token", + "created_at": "2025-07-10T18:30:00.000000+00:00", + "expires_at": "2025-08-09T18:30:00.000000+00:00", + "status": "Active" + }, + { + "hash": "def09876uvw54321...", + "description": "Service account token", + "created_at": "2025-07-10T19:00:00.000000+00:00", + "expires_at": null, + "status": "Never Expires" + } +] ``` **Example Output:** @@ -183,7 +212,19 @@ Expires: Never Shows detailed information about a specific token. Supports partial hash matching for convenience. ```bash -agent-memory token show TOKEN_HASH +agent-memory token show TOKEN_HASH [--format text|json] +``` + +When `--format json` is used, the command prints a JSON object with token details (including status) suitable for scripting and CI pipelines. The default `text` format produces human-readable output. +**JSON Output Example:** +```json +{ + "hash": "abc12345def67890xyz", + "description": "API access token", + "created_at": "2025-07-10T18:30:00.000000+00:00", + "expires_at": "2025-08-09T18:30:00.000000+00:00", + "status": "Active" +} ``` **Arguments:**