Authentication

Chucky uses JWT (JSON Web Tokens) for authentication. Tokens are created server-side with your HMAC secret and include budget limits for each user.

Token Architecture

Request Token

Your client (browser) requests a token from your backend server

Create JWT

Your server creates a JWT signed with your HMAC secret, including user ID and budget limits

Return Token

Server returns the signed JWT to the client

Use SDK

Client uses the token to connect to Chucky Cloud via the SDK

Never expose your HMAC secret to clients. Always create tokens on your server.

Creating Tokens

Basic Token

Get your Project ID and HMAC Secret from your project settings at app.chucky.cloud.

import { createToken, createBudget } from '@chucky.cloud/sdk';

const token = await createToken({
  userId: 'user-123',
  projectId: process.env.CHUCKY_PROJECT_ID,  // From portal project settings
  secret: process.env.CHUCKY_HMAC_SECRET,    // From portal project settings
  budget: createBudget({
    aiDollars: 1.00,
    computeHours: 1,
    window: 'day',
  }),
});

from chucky import create_token, create_budget
import os

token = create_token(
    user_id='user-123',
    project_id=os.environ['CHUCKY_PROJECT_ID'],  # From portal project settings
    secret=os.environ['CHUCKY_HMAC_SECRET'],     # From portal project settings
    budget=create_budget(
        ai_dollars=1.00,
        compute_hours=1,
        window='day',
    ),
)

The Project ID and HMAC Secret are separate values found in your project settings at app.chucky.cloud. The Project ID is used in JWT tokens, while the HMAC Secret is used for signing (never exposed in tokens).

Token Options

Option	Type	Required	Description
`userId`	`string`	Yes	Unique identifier for the user
`projectId`	`string`	Yes	Your project ID from portal settings
`secret`	`string`	Yes	Your HMAC secret from portal settings
`budget`	`TokenBudget`	Yes	Budget configuration
`expiresIn`	`number`	No	Token validity in seconds (default: 3600)
`permissions`	`object`	No	Optional permission constraints
`sdkConfig`	`object`	No	SDK configuration overrides

Budget Configuration

Budgets control how much each user can spend. Two types of limits:

AI Budget: Cost limit for Claude API calls (in dollars)
Compute Budget: Time limit for sandbox execution (in hours)

Budget Helper

import { createBudget } from '@chucky.cloud/sdk';

const budget = createBudget({
  aiDollars: 5.00,        // $5 AI budget
  computeHours: 2,        // 2 hours compute
  window: 'day',          // Reset window
  windowStart: new Date() // Optional: when window started
});

Budget Windows

Window	Description
`hour`	Resets every hour
`day`	Resets every 24 hours
`week`	Resets every 7 days
`month`	Resets on billing anchor day

Raw Budget Format

If you need more control, you can specify the raw budget format:

const token = await createToken({
  userId: 'user-123',
  projectId: process.env.CHUCKY_PROJECT_ID,
  secret: process.env.CHUCKY_HMAC_SECRET,
  budget: {
    ai: 5_000_000,          // 5 USD in microdollars
    compute: 7200,          // 2 hours in seconds
    window: 'day',
    windowStart: new Date().toISOString(),
  },
});

AI budget is specified in microdollars (1 USD = 1,000,000 microdollars) for precision.

Token Permissions

Restrict what users can do with their token:

const token = await createToken({
  userId: 'user-123',
  projectId: process.env.CHUCKY_PROJECT_ID,
  secret: process.env.CHUCKY_HMAC_SECRET,
  budget: createBudget({ aiDollars: 1, computeHours: 1, window: 'day' }),
  permissions: {
    tools: ['search', 'calculator'],    // Only these tools allowed
    blockedTools: ['shell', 'write'],   // These tools blocked
    maxTurns: 10,                        // Max conversation turns
    model: 'claude-sonnet-4-5-20250929', // Force specific model
  },
});

Permission Options

Option	Type	Description
`tools`	`string[]`	Whitelist of allowed tool names
`blockedTools`	`string[]`	Blacklist of blocked tool names
`maxTurns`	`number`	Maximum conversation turns
`model`	`string`	Force a specific model

SDK Config Overrides

Override client-side SDK options from the token (server-enforced):

const token = await createToken({
  userId: 'user-123',
  projectId: process.env.CHUCKY_PROJECT_ID,
  secret: process.env.CHUCKY_HMAC_SECRET,
  budget: createBudget({ aiDollars: 1, computeHours: 1, window: 'day' }),
  sdkConfig: {
    model: 'claude-sonnet-4-5-20250929',
    systemPrompt: 'You are a helpful assistant.',
    maxTurns: 5,
    maxBudgetUsd: 0.50,
    allowedTools: ['safe_tool'],
    disallowedTools: ['dangerous_tool'],
  },
});

SDK config overrides take precedence over any options passed by the client.

Token Utilities

Decode Token (No Verification)

import { decodeToken } from '@chucky.cloud/sdk';

const decoded = decodeToken(token);
console.log(decoded.sub);    // User ID
console.log(decoded.iss);    // Project ID
console.log(decoded.budget); // Budget config

Verify Token

import { verifyToken } from '@chucky.cloud/sdk';

const isValid = await verifyToken(token, process.env.HMAC_SECRET);
if (!isValid) {
  throw new Error('Invalid token signature');
}

Check Expiration

import { isTokenExpired } from '@chucky.cloud/sdk';

if (isTokenExpired(token)) {
  // Token has expired, create a new one
  const newToken = await createToken({ ... });
}

Token Payload Structure

The JWT payload contains:

interface TokenPayload {
  // Standard JWT claims
  sub: string;           // User ID
  iss: string;           // Project/Issuer ID
  exp: number;           // Expiry timestamp (Unix seconds)
  iat: number;           // Issued at timestamp

  // Chucky-specific
  budget: {
    ai: number;          // AI budget in microdollars
    compute: number;     // Compute budget in seconds
    window: string;      // Budget window type
    windowStart: string; // ISO 8601 timestamp
  };

  // Optional
  permissions?: { ... };
  sdkConfig?: { ... };
}

Best Practices

Short-lived tokens

Use short expiration times (1 hour or less) and refresh tokens as needed. This limits exposure if a token is compromised.

Per-session tokens

Create a new token for each user session rather than reusing tokens. This provides better audit trails and security.

Conservative budgets

Start with small budgets and increase based on user needs. You can always create a new token with a larger budget.

Use permissions

Restrict tools and models based on user trust level. Free users might get limited tools, while premium users get full access.

Example: Token Endpoint

Here’s a complete example of a token endpoint:

// pages/api/token.ts (Next.js example)
import { createToken, createBudget } from '@chucky.cloud/sdk';

export async function POST(req: Request) {
  // Verify user is authenticated (your auth system)
  const user = await getCurrentUser(req);
  if (!user) {
    return new Response('Unauthorized', { status: 401 });
  }

  // Get user's tier for budget limits
  const tier = user.subscriptionTier || 'free';
  const budgets = {
    free: { ai: 0.10, compute: 0.1 },
    pro: { ai: 5.00, compute: 2 },
    enterprise: { ai: 50.00, compute: 10 },
  };

  const { ai, compute } = budgets[tier];

  const token = await createToken({
    userId: user.id,
    projectId: process.env.CHUCKY_PROJECT_ID,
    secret: process.env.CHUCKY_HMAC_SECRET,
    expiresIn: 3600,
    budget: createBudget({
      aiDollars: ai,
      computeHours: compute,
      window: 'day',
    }),
    permissions: tier === 'free' ? {
      maxTurns: 5,
      blockedTools: ['shell', 'write_file'],
    } : undefined,
  });

  return Response.json({ token });
}

Getting Started

Guides

CLI

Use Cases

Advanced

Concepts

Authentication

Authentication

Token Architecture

Creating Tokens

Basic Token

Token Options

Budget Configuration

Budget Helper

Budget Windows

Raw Budget Format

Token Permissions

Permission Options

SDK Config Overrides

Token Utilities

Decode Token (No Verification)

Verify Token

Check Expiration

Token Payload Structure

Best Practices

Example: Token Endpoint

​Authentication

​Token Architecture

​Creating Tokens

​Basic Token

​Token Options

​Budget Configuration

​Budget Helper

​Budget Windows

​Raw Budget Format

​Token Permissions

​Permission Options

​SDK Config Overrides

​Token Utilities

​Decode Token (No Verification)

​Verify Token

​Check Expiration

​Token Payload Structure

​Best Practices

​Example: Token Endpoint

Authentication

Token Architecture

Creating Tokens

Basic Token

Token Options

Budget Configuration

Budget Helper

Budget Windows

Raw Budget Format

Token Permissions

Permission Options

SDK Config Overrides

Token Utilities

Decode Token (No Verification)

Verify Token

Check Expiration

Token Payload Structure

Best Practices

Example: Token Endpoint