Authentication

The Hubify API supports two authentication methods: API keys (for server-to-server) and Clerk JWT tokens (for user sessions).

API Keys

API keys are long-lived credentials for programmatic access. Create them from the CLI or web UI.

Creating an API Key

hubify auth api-key create --name "my-integration" --scope "labs:read,experiments:*"

{
  "key": "hfy_key_abc123def456ghi789",
  "name": "my-integration",
  "scopes": ["labs:read", "experiments:*"],
  "created_at": "2026-04-14T10:00:00Z",
  "expires_at": null
}

Warning: API keys are shown only once at creation. Store them securely. If lost, revoke and create a new one.

Using an API Key

curl https://api.hubify.com/v1/labs \
  -H "Authorization: Bearer hfy_key_abc123def456ghi789"

Scopes

Scope	Description
labs:read	Read lab information
labs:write	Create, update, delete labs
experiments:read	Read experiment status and results
experiments:write	Create and manage experiments
experiments:*	Full experiment access
agents:read	Read agent configuration
agents:write	Manage agents
papers:read	Read paper content
papers:write	Create and edit papers
pods:read	Read pod status
pods:write	Create and manage pods
tasks:*	Full task access
knowledge:*	Full knowledge base access
*	Full access (all scopes)

Clerk JWT Tokens

For user-facing applications, use Clerk JWT tokens obtained through the Clerk authentication flow.

Obtaining a Token

const { getToken } = useAuth();
const token = await getToken();

fetch('https://api.hubify.com/v1/labs', {
  headers: { 'Authorization': `Bearer ${token}` }
});

Token Refresh

Clerk tokens expire after 60 seconds. Use the Clerk SDK's automatic refresh mechanism for long-lived sessions.

Environment Variables

Variable	Description
HUBIFY_API_KEY	API key for programmatic access
HUBIFY_TOKEN	Short-lived auth token
CLERK_SECRET_KEY	Clerk secret for server-side verification

Security Best Practices

• Use the narrowest possible scopes for API keys
• Rotate API keys regularly (every 90 days recommended)
• Never commit API keys to version control
• Use environment variables for all credentials
• Prefer Clerk JWT tokens for user-facing applications
• Revoke compromised keys immediately with hubify auth api-key revoke <key>