**JWT Tokens** (User Sessions)
**Use for:** Browser sessions, interactive work
```bash
POST /api/v1/users/auth/login
```
**Returns:**
- `token` (access, 1 day)
- `refreshToken` (7 days)
**Characteristics:**
- ✅ Short-lived (secure)
- ✅ Refresh-able (no re-login)
- ✅ User-specific
- ❌ Not ideal for automation
**Auth Tokens** (Automation)
**Use for:** Scripts, AI agents, CI/CD, integrations
```bash
POST /api/v1/auth/tokens
```
**Returns:**
- `hdy_...` token (long-lived)
**Characteristics:**
- ✅ Long-lived (configurable)
- ✅ IP whitelist support
- ✅ Revocable anytime
- ✅ Per-token permissions
- ✅ Ideal for automation
**Best Practice:** Use Auth Tokens for any automation, AI agents, or scripts. Never put user credentials in code. Create a dedicated token with appropriate expiration and IP restrictions.
---
## Authentication Workflow
### For Interactive Use (Browser/CLI)
**Step 1: Login**
The login endpoint accepts **either** an `email` or a `username` — only `password` is required. Use whichever identifier you have. The CLI exposes both as separate flags (`--email` and `--username`).
```bash
# Login with email and password (or use --username instead of --email)
hoody auth login --email you@example.com --password your_password
```
```typescript
import { HoodyClient } from '@hoody-ai/hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.icu' });
// Login with credentials — pass `email` OR `username` (not both required)
const auth = await client.api.authentication.login({
email: 'you@example.com',
password: 'your_password'
});
console.log(auth.data.token); // JWT access token
console.log(auth.data.refreshToken); // Refresh token
```
```bash
# Provide EITHER email OR username (only password is required)
curl -X POST "https://api.hoody.icu/api/v1/users/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "your_password"}'
# Alternative: -d '{"username": "your_username", "password": "your_password"}'
```
**Response:**
```json
{
"statusCode": 200,
"message": "Login successful",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "63f8b0e5c9a1b2d3e4f5a6b7",
"username": "your_username",
"alias": "Your Display Name",
"is_banned": false,
"created_at": "2025-10-21T10:00:00.000Z",
"updated_at": "2025-10-21T10:00:00.000Z"
}
}
}
```
**Step 2: Use Access Token**
```bash
# CLI stores the token automatically after login
hoody projects list
```
```typescript
// Pass token to client constructor
const client = new HoodyClient({
baseURL: 'https://api.hoody.icu',
token: auth.data.token
});
const projects = await client.api.projects.list();
```
```bash
# Include token in Authorization header
curl "https://api.hoody.icu/api/v1/projects" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
**Step 3: Refresh When Expired**
```bash
# CLI handles token refresh automatically
# If your session expired, simply re-login
hoody auth login --username your_username --password your_password
```
```typescript
// Refresh the access token
const refreshed = await client.api.authentication.refreshToken({
refreshToken: auth.data.refreshToken
});
console.log(refreshed.data.token); // New access token
```
```bash
curl -X POST "https://api.hoody.icu/api/v1/users/auth/refresh" \
-H "Content-Type: application/json" \
-d '{"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'
```
**Returns:** New access token + new refresh token (both rotated for security)
---
### For Automation & AI (Recommended)
**Step 1: Create Auth Token** (one-time setup)
```bash
# Login first
hoody auth login --username your_username --password your_password
# Create a long-lived automation token with IP whitelist
hoody auth create \
--alias "Production Automation Token" \
--ip-whitelist "203.0.113.10,203.0.113.20" \
--expires-at "2027-04-12T00:00:00Z"
```
```typescript
import { HoodyClient } from '@hoody-ai/hoody-sdk';
// Login first to get JWT
const client = new HoodyClient({ baseURL: 'https://api.hoody.icu' });
const auth = await client.api.authentication.login({
username: 'your_username',
password: 'your_password'
});
// Create auth token using JWT
const jwtClient = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: auth.data.token });
const token = await jwtClient.api.authTokens.create({
alias: 'Production Automation Token',
ip_whitelist: ['203.0.113.10', '203.0.113.20'],
expires_at: '2027-04-12T00:00:00Z'
});
console.log(token.data.token); // hdy_... — save this immediately!
```
```bash
# Login to get JWT
curl -X POST "https://api.hoody.icu/api/v1/users/auth/login" \
-H "Content-Type: application/json" \
-d '{"username": "your_username", "password": "your_password"}'
# Create a long-lived automation token
curl -X POST "https://api.hoody.icu/api/v1/auth/tokens" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{
"alias": "Production Automation Token",
"ip_whitelist": ["203.0.113.10", "203.0.113.20"],
"expires_at": "2027-04-12T00:00:00Z"
}'
```
**Response:**
```json
{
"statusCode": 201,
"message": "Auth token created successfully",
"data": {
"token": "hdy_abc123XyZ456...",
"id": "63f8b0e5c9a1b2d3e4f5a6b7",
"alias": "Production Automation Token",
"prefix": "hdy_",
"ip_whitelist": ["203.0.113.10", "203.0.113.20"],
"expires_at": "2027-04-12T00:00:00.000Z",
"is_enabled": true,
"last_used_at": null,
"last_used_ip": null,
"created_at": "2025-11-09T15:00:00.000Z",
"updated_at": "2025-11-09T15:00:00.000Z"
}
}
```
**Save this token immediately!** The full `token` value (`hdy_abc123...`) is **only shown once** during creation. You cannot retrieve it again.
**Step 2: Use Auth Token** (forever, until it expires or is revoked)
```bash
# Store token and use with CLI
export HOODY_TOKEN="hdy_abc123XyZ456..."
# All subsequent commands use this token
hoody projects list
hoody containers list
```
```typescript
// Use auth token in SDK client
const client = new HoodyClient({
baseURL: 'https://api.hoody.icu',
token: process.env.HOODY_TOKEN // hdy_abc123XyZ456...
});
// All API calls are authenticated
const projects = await client.api.projects.list();
```
```bash
# Store in environment variable (never hardcode)
export HOODY_TOKEN="hdy_abc123XyZ456..."
# Use in all API requests
curl "https://api.hoody.icu/api/v1/projects" \
-H "Authorization: Bearer $HOODY_TOKEN"
```
**Benefits:**
- ✅ No credentials in code (secure)
- ✅ IP whitelist enforcement (restrict to specific IPs)
- ✅ Expiration control (ISO 8601 date, or never)
- ✅ Instant revocation (disable or delete token)
- ✅ Audit trail (last_used_at, last_used_ip)
---
## Auth Token Management
### Creating Tokens with Security Features
**IP Whitelisting:**
**Multiple formats for expiration:**
```json
{
"expires_at": "2026-12-31T23:59:59Z"
}
```
```json
{
"expires_at": 1735689599
}
```
```json
{
"expires_at": null
}
```
### Listing and Auditing Tokens
```bash
# List all your auth tokens
hoody auth list
```
```typescript
const tokens = await client.api.authTokens.list();
tokens.data.forEach(t => {
console.log(t.alias, t.is_enabled, t.last_used_at);
});
```
```bash
curl "https://api.hoody.icu/api/v1/auth/tokens" \
-H "Authorization: Bearer $HOODY_TOKEN"
```
**Response shows usage tracking:**
```json
{
"data": [
{
"id": "63f8b0e5c9a1b2d3e4f5a6b7",
"alias": "CI/CD Pipeline",
"prefix": "hdy_",
"ip_whitelist": ["203.0.113.50"],
"expires_at": "2026-02-07T15:00:00.000Z",
"is_enabled": true,
"last_used_at": "2025-11-09T14:30:00.000Z",
"last_used_ip": "203.0.113.50",
"created_at": "2025-11-09T10:00:00.000Z",
"updated_at": "2025-11-09T14:30:00.000Z"
}
]
}
```
**Audit your tokens:**
- Check `last_used_at` to identify unused tokens
- Verify `last_used_ip` matches expected sources
- Review `ip_whitelist` restrictions
### Revoking Tokens
**Disable without deleting:**
```bash
# Disable a token without deleting it
hoody auth update $TOKEN_ID --enabled false
```
```typescript
await client.api.authTokens.update(tokenId, { is_enabled: false });
```
```bash
curl -X PUT "https://api.hoody.icu/api/v1/auth/tokens/$TOKEN_ID" \
-H "Authorization: Bearer $HOODY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"is_enabled": false}'
```
**Permanently delete:**
```bash
# Permanently delete a token
hoody auth delete $TOKEN_ID
```
```typescript
await client.api.authTokens.delete(tokenId);
```
```bash
curl -X DELETE "https://api.hoody.icu/api/v1/auth/tokens/$TOKEN_ID" \
-H "Authorization: Bearer $HOODY_TOKEN"
```
---
## Security Best Practices
### 1. Never Hardcode Credentials
```javascript
// NEVER do this
const response = await fetch('https://api.hoody.icu/api/v1/projects', {
headers: {
'Authorization': 'Bearer hdy_abc123hardcoded'
}
});
```
```javascript
// Use environment variables
const response = await fetch('https://api.hoody.icu/api/v1/projects', {
headers: {
'Authorization': `Bearer ${process.env.HOODY_TOKEN}`
}
});
```
### 2. Use IP Whitelisting
**Restrict tokens to specific sources:**
**If token is leaked:** It won't work from other IPs.
### 3. Set Expiration Appropriately
**Short-lived for temporary access:**
```json
{
"alias": "Contractor Access",
"expires_at": "2026-05-12T00:00:00Z"
}
```
**Long-lived for permanent infrastructure:**
```json
{
"alias": "Production Services",
"expires_at": "2027-04-12T00:00:00Z"
}
```
**Review and rotate regularly.**
### 4. Create Dedicated Tokens per Service
**Don't share one token across multiple systems:**
```bash
# Create separate tokens
POST /api/v1/auth/tokens { "alias": "GitHub Actions CI", ... }
POST /api/v1/auth/tokens { "alias": "Monitoring System", ... }
POST /api/v1/auth/tokens { "alias": "AI Agent Orchestrator", ... }
```
**If one service is compromised:** Revoke only that token, others continue working.
---
## For AI Agents
**The Auth Token system is designed for AI orchestration:**
```javascript
// AI agent configuration (environment variables)
const HOODY_TOKEN = process.env.HOODY_TOKEN; // hdy_... token
const HOODY_API = 'https://api.hoody.icu';
// AI can now orchestrate infrastructure
async function aiAgentWorkflow(task) {
const headers = {
'Authorization': `Bearer ${HOODY_TOKEN}`,
'Content-Type': 'application/json'
};
// AI decides: "Need a container to process this task"
const container = await fetch(`${HOODY_API}/api/v1/projects/${projectId}/containers`, {
method: 'POST',
headers,
body: JSON.stringify({
name: `ai-task-${Date.now()}`,
server_id: 'your-server-id',
hoody_kit: true
})
}).then(r => r.json());
// Wait for container to be running
await waitForStatus(container.data.id, 'running');
// Get container URLs and use them
const terminalUrl = `https://${projectId}-${container.data.id}-terminal-1.${container.data.server_name}.containers.hoody.icu`;
// AI executes commands in the new container
await fetch(`${terminalUrl}/execute`, {
method: 'POST',
body: JSON.stringify({ command: task.command })
});
// AI snapshots when done
await fetch(`${HOODY_API}/api/v1/containers/${container.data.id}/snapshots`, {
method: 'POST',
headers,
body: JSON.stringify({ alias: `task-${task.id}` })
});
return container;
}
```
**The AI only needs:**
1. A Hoody Auth Token (environment variable)
2. Understanding of HTTP (it already has this)
No SDK. No training. Just HTTP.
---
## Token Comparison
| Feature | JWT (Login) | Auth Token (hdy_...) |
|---------|-------------|----------------------|
| **Lifetime** | 1 day (access)