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
}

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://www.hubify.com/api/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

import { useAuth } from '@clerk/nextjs';

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

fetch('https://www.hubify.com/api/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>

Overview

Labs

Data

Compute

Lab Ops

Authentication

Authentication

API Keys

Creating an API Key

Using an API Key

Scopes

Clerk JWT Tokens

Obtaining a Token

Token Refresh

Environment Variables

Security Best Practices

​Authentication

​API Keys

​Creating an API Key

​Using an API Key

​Scopes

​Clerk JWT Tokens

​Obtaining a Token

​Token Refresh

​Environment Variables

​Security Best Practices

Authentication

API Keys

Creating an API Key

Using an API Key

Scopes

Clerk JWT Tokens

Obtaining a Token

Token Refresh

Environment Variables

Security Best Practices