Hyperfold AI

Authentication

Secure your CLI sessions with OAuth, service accounts, or API keys.

Overview

The Hyperfold CLI supports multiple authentication methods to suit different use cases:

MethodBest ForExpiration
Interactive OAuthLocal development, manual operations1 hour (auto-refresh)
Service AccountCI/CD pipelines, server-side automation1 hour (auto-refresh)
API KeySimple integrations, scriptsConfigurable (up to 1 year)

Interactive Login

For local development, use browser-based OAuth authentication:

# Start interactive authentication
$ hyperfold auth login
> Opening browser for authentication...
> Waiting for authorization...
✓ Authentication successful!
  User: developer@acme-sports.com
  Project: proj_acme_sports
  Environment: development
# Verify authentication status
$ hyperfold auth status
AUTHENTICATED
  Method:      OAuth 2.0 (Google)
  Identity:    developer@acme-sports.com
  Project:     proj_acme_sports
  Expires:     2025-12-20T10:30:00Z
  Permissions: admin

Service Accounts

For automated workflows, use GCP service account credentials:

# Authenticate with a service account key file
$ hyperfold auth login --service-account=./service-account.json
> [Auth] Reading service account credentials...
> [Auth] Validating permissions...
✓ Authenticated as hyperfold-sa@acme-sports.iam.gserviceaccount.com
# Or use environment variable
$ export GOOGLE_APPLICATION_CREDENTIALS=./service-account.json
$ hyperfold auth login --service-account
# For CI/CD: use base64-encoded credentials
$ export HYPERFOLD_CREDENTIALS=$(cat service-account.json | base64)
$ hyperfold auth login --credentials-env

Creating a Service Account

Create a dedicated service account in the GCP Console:

  1. Navigate to IAM & Admin → Service Accounts
  2. Click "Create Service Account"
  3. Name it hyperfold-cli or similar
  4. Grant the "Hyperfold Developer" role
  5. Create and download a JSON key file

API Keys

API keys provide a simpler authentication method for scripts and integrations:

# Generate an API key for programmatic access
$ hyperfold auth api-key create --name="ci-pipeline" --expires="30d"
> [Auth] Creating API key...
✓ API key created
  Name:       ci-pipeline
  Key:        hf_live_abc123xyz...
  Expires:    2026-01-18T00:00:00Z
  Scopes:     catalog:read, catalog:write, agent:deploy
⚠ Store this key securely. It will not be shown again.
# Use API key for authentication
$ hyperfold auth login --api-key="hf_live_abc123xyz..."
# Or via environment variable
$ export HYPERFOLD_API_KEY="hf_live_abc123xyz..."
$ hyperfold catalog list

API Key Scopes

Limit API key permissions with scopes:

ScopePermissions
catalog:readRead product catalog
catalog:writeImport, update, delete products
agent:readList agents, view logs
agent:deployDeploy and configure agents
payments:readView payment configuration
payments:writeConfigure payment providers

Token Management

Manage authentication tokens and sessions:

# Check token expiration
$ hyperfold auth status --check-expiry
Token expires in 45 minutes.
# Refresh token proactively
$ hyperfold auth refresh
> [Auth] Refreshing access token...
✓ Token refreshed. New expiry: 2025-12-19T12:30:00Z
# Revoke current session
$ hyperfold auth logout
> [Auth] Revoking access token...
> [Auth] Clearing local credentials...
✓ Logged out successfully

Permissions

View your current role and permissions:

# List available roles
$ hyperfold auth roles list
ROLE                DESCRIPTION
admin               Full access to all resources
developer           Deploy agents, manage catalog
viewer              Read-only access
billing             Access to billing and usage data
# Check current permissions
$ hyperfold auth permissions
RESOURCE          CREATE  READ  UPDATE  DELETE
agents            ✓       ✓     ✓       ✓
catalog           ✓       ✓     ✓       ✓
payments          ✓       ✓     ✓       ○
integrations      ✓       ✓     ✓       ✓
billing           ○       ✓     ○       ○