> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API authentication, API keys, Clerk JWT tokens, scopes, and security best practices.

# 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

```bash theme={null}
hubify auth api-key create --name "my-integration" --scope "labs:read,experiments:*"
```

```json theme={null}
{
  "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.
</Warning>

### Using an API Key

```bash theme={null}
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

```typescript theme={null}
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>`