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:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 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
Interactive login uses Google OAuth by default. Your organization can configure additional identity providers (Okta, Azure AD) in the Hyperfold Console.

Service Accounts

For automated workflows, use GCP service account credentials:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 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
Store service account keys securely. Use GCP Secret Manager or your CI/CD platform's secret storage for production deployments.

API Keys

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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 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:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 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:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 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           ○       ✓     ○       ○
Now that you're authenticated, learn about managing your product catalog.