Site Token Management Commands¶

The site tokens command group provides comprehensive token management for site authentication and access control.

Overview¶

Token management commands allow you to: - View and rotate master tokens - Create HTTP access tokens with specific permissions - Decode HTTP access tokens - Revoke HTTP access tokens by token value or hash - List, delete, backup, and restore access-token history - Control access with time-limited tokens

Token Types¶

Master Token¶

Purpose: Full administrative access to a site
Lifetime: Permanent (until rotated)
Permissions: Read/write access to all content and configuration
Use: CLI operations, direct API access, creating HTTP access tokens
Security: Keep highly secure, rotate regularly

HTTP Access Token¶

Purpose: Time-limited, permission-scoped access
Lifetime: Configurable (default: 24 hours)
Permissions: Read-only or read/write
Use: Temporary access, sharing, automation, web applications
Security: Expires automatically, limited scope
Revocation: Invalidated if the site's master token is rotated or revoked

Global Flags¶

--debug, -d, --verbose - Show debug information
--insecure, -k - Skip TLS certificate verification
--force, -f, -y, --yes - Force operations without prompting
--output, -o - Output format: json, yaml, or table

Quick Examples (Latest Commands)¶

# Revoke by token value
sitesctl site --space myspace --name mysite \
  tokens access-token revoke --token "abc123..."

# Revoke by token hash
sitesctl site --space myspace --name mysite \
  tokens access-token revoke --hash a1b2c3d4...

# List token history
sitesctl site --space myspace --name mysite \
  tokens access-token history list

# Delete one history entry
sitesctl site --space myspace --name mysite \
  tokens access-token history delete --hash a1b2c3d4...

# Backup and restore token history
sitesctl site --space myspace --name mysite \
  tokens access-token history backup
sitesctl site --space myspace --name mysite \
  tokens access-token history restore

Master Token Commands¶

`sitesctl site tokens master-token show`¶

Display the site's master token.

Usage:

sitesctl site --space <space> --name <name> tokens master-token show

Examples:

# Show master token
sitesctl site --space myspace --name mysite \
  tokens master-token show

# Show as JSON
sitesctl site --space myspace --name mysite \
  tokens master-token show --output json

# Save to variable
token=$(sitesctl site --space myspace --name mysite \
  tokens master-token show --output json | jq -r '.token')

Output: - Decoded master token - Token creation date - Token status

Security Note: The master token provides full access to your site. Keep it secure.

`sitesctl site tokens master-token rotate`¶

Revoke the current master token and issue a new one.

Usage:

sitesctl site --space <space> --name <name> tokens master-token rotate

Examples:

# Rotate master token
sitesctl site --space myspace --name mysite \
  tokens master-token rotate

# Rotate without confirmation
sitesctl site --space myspace --name mysite \
  tokens master-token rotate --force

# Rotate and save new token
new_token=$(sitesctl site --space myspace --name mysite \
  tokens master-token rotate --force --output json | jq -r '.token')

What it does: - Invalidates the current master token - Generates a new master token - Returns the new token

⚠️ Important: - Old token becomes invalid immediately - Update any systems using the old token - Save the new token securely - HTTP access tokens created with the old master token are invalidated

When to rotate: - Regular security maintenance (every 90 days recommended) - After employee departure - If token is compromised or exposed - Before sharing access (create HTTP access token instead)

HTTP Access Token Commands¶

`sitesctl site tokens access-token create`¶

Create a time-limited HTTP access token.

Usage:

sitesctl site --space <space> --name <name> tokens access-token create --identifier <id> [flags]

Flags:

--identifier (required) - Identifier for the token
Used in logs and auditing
Descriptive name (e.g., "ci-pipeline", "temp-access")
--duration - Token lifetime in seconds
Default: 86400 (24 hours)
Maximum depends on server configuration
--permission - Access permission level
Values: r (read-only) or rw (read/write)
Default: r

Examples:

# Create read-only token (24 hour default)
sitesctl site --space myspace --name mysite \
  tokens access-token create --identifier "temp-access"

# Create read/write token for 1 hour
sitesctl site --space myspace --name mysite \
  tokens access-token create \
  --identifier "deployment" \
  --duration 3600 \
  --permission rw

# Create read-only token for 7 days
sitesctl site --space myspace --name mysite \
  tokens access-token create \
  --identifier "readonly-share" \
  --duration 604800 \
  --permission r

# Create token and save to variable
access_token=$(sitesctl site --space myspace --name mysite \
  tokens access-token create \
  --identifier "api-access" \
  --output json | jq -r '.token')

Common Duration Values:

Duration	Seconds	Use Case
1 hour	3600	Quick temporary access
6 hours	21600	Work session
24 hours	86400	Daily automation (default)
7 days	604800	Weekly processes
30 days	2592000	Monthly access

Permission Levels:

Permission	Can Read	Can Write	Use Case
`r`	Yes	No	Sharing, downloads, public access
`rw`	Yes	Yes	Uploads, CI/CD, content management

Use Cases: - Sharing site access temporarily - CI/CD pipeline authentication - Automated content updates - Third-party integrations - Time-limited API access - Public read-only access

`sitesctl site tokens access-token decode`¶

Decode and verify an HTTP access token.

Usage:

sitesctl site --space <space> --name <name> tokens access-token decode --token <token>

Flags: - --token (required) - Token string to decode

Examples:

# Decode a token
sitesctl site --space myspace --name mysite \
  tokens access-token decode --token "abc123..."

# Decode with JSON output
sitesctl site --space myspace --name mysite \
  tokens access-token decode \
  --token "abc123..." \
  --output json

Output Information: - Token validity status - Expiration date/time - Permission level (read/read-write) - Identifier - Associated site - Creation date

Use Cases: - Verify token before use - Check expiration date - Confirm permission level - Audit token usage - Debug authentication issues

`sitesctl site tokens access-token revoke`¶

Revoke an HTTP access token by token string or token hash.

Usage:

sitesctl site --space <space> --name <name> tokens access-token revoke [--token <token> | --hash <sha256>]

Flags: - --token - Token string to revoke - --hash - SHA256 hash of the token to revoke

Examples:

# Revoke by token value
sitesctl site --space myspace --name mysite \
  tokens access-token revoke --token "abc123..."

# Revoke by hash
sitesctl site --space myspace --name mysite \
  tokens access-token revoke --hash a1b2c3d4...

Important: - Provide exactly one of --token or --hash.

Token History Commands¶

`sitesctl site tokens access-token history list`¶

Retrieve token history with optional filters.

Usage:

sitesctl site --space <space> --name <name> tokens access-token history list [flags]

Flags: - --identifier - Filter by token identifier - --permission - Filter by permission: r or rw - --expiring-within - Filter tokens expiring within N seconds - --include-expired - Include expired tokens (default: false)

Examples:

# List all non-expired token history entries
sitesctl site --space myspace --name mysite \
  tokens access-token history list

# Filter by identifier and permission
sitesctl site --space myspace --name mysite \
  tokens access-token history list --identifier "ci-pipeline" --permission rw

# Show entries expiring within 7 days, including expired
sitesctl site --space myspace --name mysite \
  tokens access-token history list --expiring-within 604800 --include-expired

`sitesctl site tokens access-token history delete`¶

Delete a token history entry by SHA256 hash.

Usage:

sitesctl site --space <space> --name <name> tokens access-token history delete --hash <sha256>

Flags: - --hash (required) - SHA256 hash of the history entry

Examples:

# Delete an entry by hash
sitesctl site --space myspace --name mysite \
  tokens access-token history delete --hash a1b2c3d4...

# Delete without confirmation prompt
sitesctl site --space myspace --name mysite \
  tokens access-token history delete --hash a1b2c3d4... --force

`sitesctl site tokens access-token history backup`¶

Create a backup of all token history entries.

Usage:

sitesctl site --space <space> --name <name> tokens access-token history backup

Examples:

# Create backup
sitesctl site --space myspace --name mysite \
  tokens access-token history backup

# Create backup and parse metadata
sitesctl site --space myspace --name mysite \
  tokens access-token history backup --output json

`sitesctl site tokens access-token history restore`¶

Restore token history from the latest backup.

Usage:

sitesctl site --space <space> --name <name> tokens access-token history restore

Examples:

# Restore token history
sitesctl site --space myspace --name mysite \
  tokens access-token history restore

# Restore without confirmation prompt
sitesctl site --space myspace --name mysite \
  tokens access-token history restore --force

⚠️ Important: - Restore is destructive: current token history entries are replaced by backup data. - Use backup before restore to preserve current state.

Token Security Best Practices¶

Master Tokens¶

Keep Secure
Store in password managers
Never commit to version control
Don't share in plaintext
Use environment variables in scripts
Rotate Regularly
Every 90 days minimum
After team changes
When security concerns arise
Use automation for rotation
Limit Exposure
Use HTTP access tokens for sharing
Restrict to necessary systems
Use CI/CD secrets management
Monitor usage logs

HTTP Access Tokens¶

Principle of Least Privilege
Use read-only when possible
Shortest duration needed
Specific identifiers for tracking
Expiration Strategy
Match duration to task
Don't create long-lived tokens unnecessarily
Recreate instead of extending
Identifier Best Practices
Use descriptive names
Include purpose and date
Track in documentation
Examples: ci-deploy-2024, temp-share-user1

Common Workflows¶

Secure CI/CD Setup¶

#!/bin/bash
# Create read/write token for CI/CD

space="myspace"
name="mysite"

# Create 7-day token for deployments
token=$(sitesctl site --space "$space" --name "$name" \
  tokens access-token create \
  --identifier "github-actions-$(date +%Y%m)" \
  --duration 604800 \
  --permission rw \
  --output json | jq -r '.token')

# Set as GitHub secret (using gh CLI)
echo "$token" | gh secret set SITES_TOKEN --repo myorg/myrepo

echo "Token created and stored in GitHub secrets"
echo "Token expires in 7 days"

Temporary Read Access¶

#!/bin/bash
# Give temporary read access to a colleague

space="myspace"
name="mysite"

# Create 24-hour read token
token=$(sitesctl site --space "$space" --name "$name" \
  tokens access-token create \
  --identifier "share-colleague-$(date +%Y%m%d)" \
  --duration 86400 \
  --permission r \
  --output json | jq -r '.token')

echo "Share this token (expires in 24 hours):"
echo "$token"
echo ""
echo "They can use it with:"
echo "sitesctl site --space $space --name $name --api-authentication-token $token content list"

Token Rotation Script¶

#!/bin/bash
# Rotate master token and update stored token

space="myspace"
name="mysite"

echo "Rotating master token..."

# Rotate and get new token
new_token=$(sitesctl site --space "$space" --name "$name" \
  tokens master-token rotate --force --output json | jq -r '.token')

# Update stored token
sitesctl auth site-token \
  --space "$space" \
  --name "$name" \
  --token "$new_token"

# Store in password manager (example using pass)
echo "$new_token" | pass insert -e "sites/${space}/${name}/master-token"

echo "Master token rotated and stored"

Audit Token Usage¶

#!/bin/bash
# Check all active HTTP access tokens

space="myspace"
name="mysite"

# This would list tokens if API supported it
# Current workaround: track token identifiers manually

echo "Created tokens (manual tracking):"
cat token-registry.txt

echo ""
echo "To verify a token:"
echo "sitesctl site --space $space --name $name tokens access-token decode --token <TOKEN>"

Using Tokens¶

With CLI¶

Using master token:

# Option 1: Store with auth site-token (recommended)
sitesctl auth site-token --space myspace --name mysite --token <master-token>
sitesctl site --space myspace --name mysite content list

# Option 2: Use inline
sitesctl site --space myspace --name mysite \
  --api-authentication-token <master-token> \
  content list

# Option 3: Environment variable
export MASTER_TOKEN="<master-token>"
sitesctl site --space myspace --name mysite content list

Using HTTP access token:

# Same methods as master token
sitesctl site --space myspace --name mysite \
  --api-authentication-token <access-token> \
  content list --path /

With Web Browser¶

HTTP access tokens for downloads:

https://sites.ecmwf.int/{space}/{name}/path/to/file?token=<access-token>

With curl¶

# Download with access token
curl -H "Authorization: Bearer <access-token>" \
  https://sites.ecmwf.int/{space}/{name}/api/v2/content/

# Upload with access token (rw permission required)
curl -X POST \
  -H "Authorization: Bearer <access-token>" \
  -F "file=@localfile.txt" \
  https://sites.ecmwf.int/{space}/{name}/api/v2/content/

In Scripts¶

# Python example
import requests

token = "your-access-token"
space = "myspace"
name = "mysite"
url = f"https://sites.ecmwf.int/{space}/{name}/api/v2/content/"

headers = {"Authorization": f"Bearer {token}"}
response = requests.get(url, headers=headers)
files = response.json()

Scripting Examples¶

Token Management Dashboard¶

#!/bin/bash
# Display token information

space="myspace"
name="mysite"

echo "=== Token Status for ${space}/${name} ==="
echo ""

echo "Master Token:"
sitesctl site --space "$space" --name "$name" \
  tokens master-token show

echo ""
echo "To create a new HTTP access token:"
echo "sitesctl site --space $space --name $name tokens access-token create --identifier <name>"

Automated Token Distribution¶

#!/bin/bash
# Create tokens for multiple users

space="myspace"
name="mysite"
users=("alice" "bob" "charlie")

for user in "${users[@]}"; do
  echo "Creating token for $user..."

  token=$(sitesctl site --space "$space" --name "$name" \
    tokens access-token create \
    --identifier "user-${user}-$(date +%Y%m)" \
    --duration 2592000 \
    --permission r \
    --force \
    --output json | jq -r '.token')

  # Send via email or secure channel
  echo "Token for $user: $token" > "token-${user}.txt"

  # Optionally email it
  # echo "Your access token (expires in 30 days): $token" | \
  #   mail -s "Site Access Token" "${user}@example.com"
done

echo "Tokens created and saved to token-*.txt files"

Troubleshooting¶

Cannot Retrieve Master Token¶

Problem: Permission denied when trying to show master token

Solutions: - Verify you're the owner or admin - Check authentication: sitesctl auth whoami - Login if needed: sitesctl auth login

Token Expired¶

Problem: HTTP access token no longer works

Solutions: - Decode token to check expiration - Create a new token with appropriate duration - Consider automation for token renewal

Wrong Permissions¶

Problem: Cannot upload with HTTP access token

Solutions: - Verify token permission: decode the token - Create new token with rw permission - Ensure you're using the right token

Token Rotation Issues¶

Problem: Systems stop working after rotation

Solutions: - Update all systems using the old token - Keep inventory of token usage - Rotate during maintenance windows - Test new token before rotating

Site Token Management Commands¶

Overview¶

Token Types¶

Master Token¶

HTTP Access Token¶

Global Flags¶

Quick Examples (Latest Commands)¶

Master Token Commands¶

sitesctl site tokens master-token show¶

sitesctl site tokens master-token rotate¶

HTTP Access Token Commands¶

sitesctl site tokens access-token create¶

sitesctl site tokens access-token decode¶

sitesctl site tokens access-token revoke¶

Token History Commands¶

sitesctl site tokens access-token history list¶

sitesctl site tokens access-token history delete¶

sitesctl site tokens access-token history backup¶

sitesctl site tokens access-token history restore¶

Token Security Best Practices¶

Master Tokens¶

HTTP Access Tokens¶

Common Workflows¶

Secure CI/CD Setup¶

Temporary Read Access¶

Token Rotation Script¶

Audit Token Usage¶

Using Tokens¶

With CLI¶

With Web Browser¶

With curl¶

In Scripts¶

Scripting Examples¶

Token Management Dashboard¶

Automated Token Distribution¶

Troubleshooting¶

Cannot Retrieve Master Token¶

Token Expired¶

Wrong Permissions¶

Token Rotation Issues¶

See Also¶

`sitesctl site tokens master-token show`¶

`sitesctl site tokens master-token rotate`¶

`sitesctl site tokens access-token create`¶

`sitesctl site tokens access-token decode`¶

`sitesctl site tokens access-token revoke`¶

`sitesctl site tokens access-token history list`¶

`sitesctl site tokens access-token history delete`¶

`sitesctl site tokens access-token history backup`¶

`sitesctl site tokens access-token history restore`¶