API Reference

Agent Sessions

Oblien manages all session infrastructure for your end users. You only need to create sessions on your backend - we handle storage, rate limiting, guest tracking, and token management.

Overview

How It Works:

  1. Backend - Create session using your Client ID/Secret (server-side only)
  2. Oblien - Manages session storage, rate limiting, and guest tracking
  3. Frontend - Receives token to interact with agents via Chat SDK

What We Manage:

  • Session storage and persistence
  • Rate limiting (per user/guest)
  • Guest tracking (IP + fingerprint)
  • Token generation and refresh
  • Session history and chat data

What You Do:

  • Create sessions on your backend (one API call)
  • Send tokens to your frontend
  • Frontend uses tokens to chat (no client credentials needed)

Security: Never expose your Client ID or Client Secret in frontend code. Session creation must always happen on your backend server. Only the session token should be sent to the frontend.

API Usage

Create Session

Create a chat session for an authenticated user. Must be called from your backend using Client ID/Secret. Use namespace to organize sessions by workspace/app, and endUserId to track individual users within that namespace.

import { OblienClient } from 'oblien';
import { OblienChat } from 'oblien/chat';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const chat = new OblienChat(client);

const session = await chat.createSession({
  agentId: 'agent-123',
  namespace: 'production',
  endUserId: 'user-789'
});

console.log(session);
const response = await fetch('https://api.oblien.com/ai/session/create', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: 'agent-123',
    namespace: 'production',
    end_user_id: 'user-789',
    with_token: true
  })
});

const session = await response.json();
console.log(session);
curl -X POST https://api.oblien.com/ai/session/create \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-123",
    "namespace": "production",
    "end_user_id": "user-789",
    "with_token": true
  }'

Response:

{
  "success": true,
  "sessionId": "session-abc123",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh-xyz789",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "agentId": "agent-123",
  "namespace": "production"
}

List Sessions

Get all sessions for the authenticated client. Filter by namespace to get sessions for a specific workspace/app, or by endUserId to get sessions for a specific user.

const sessions = await chat.listSessions({
  namespace: 'production',
  endUserId: 'user-789',
  limit: 20,
  offset: 0
});

console.log(sessions);
const response = await fetch('https://api.oblien.com/ai/session/list?namespace=production&end_user_id=user-789&limit=20', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const sessions = await response.json();
console.log(sessions);
curl -X GET "https://api.oblien.com/ai/session/list?namespace=production&end_user_id=user-789&limit=20" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

[
  {
    "sessionId": "session-abc123",
    "agentId": "agent-123",
    "namespace": "production",
    "endUserId": "user-789",
    "title": "New Conversation",
    "createdAt": "2024-01-15T10:00:00Z",
    "lastActiveAt": "2024-01-15T11:30:00Z"
  }
]

Get Session Details

Get session information including metadata, agent ID, namespace, and creation date.

const session = await chat.getSession('session-abc123');
console.log(session);
const response = await fetch('https://api.oblien.com/ai/session/session-abc123', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const session = await response.json();
console.log(session);
# Get session details
curl -X GET "https://api.oblien.com/ai/session/session-abc123" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "sessionId": "session-abc123",
  "agentId": "agent-123",
  "namespace": "production",
  "endUserId": "user-789",
  "title": "New Conversation",
  "createdAt": "2024-01-15T10:00:00Z",
  "lastActiveAt": "2024-01-15T11:30:00Z",
  "isGuest": false
}

Get Session History

Get chat history for a session. Client-side endpoint - uses session token. For server-side, use the session ID endpoint.

const history = await chat.getHistory({
  token: sessionToken,
  namespace: 'production',
  limit: 50,
  offset: 0
});

console.log(history);
const response = await fetch('https://api.oblien.com/ai/session/history?namespace=production&limit=50', {
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
curl -X GET "https://api.oblien.com/ai/session/history?namespace=production&limit=50" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Response:

{
  "success": true,
  "history": [
    {
      "role": "user",
      "content": "Hello, how can you help?",
      "timestamp": "2024-01-15T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "I can help you with...",
      "timestamp": "2024-01-15T10:00:05Z"
    }
  ],
  "has_more": false,
  "token_usage": {
    "total": 150,
    "prompt": 50,
    "completion": 100
  }
}

Refresh Session Token

Refresh an expired session token using the refresh token. Client-side endpoint - uses refresh token.

const tokens = await chat.refreshToken(refreshToken);
console.log(tokens);
const response = await fetch('https://api.oblien.com/ai/session/token/refresh', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${refreshToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
curl -X POST https://api.oblien.com/ai/session/token/refresh \
  -H "Authorization: Bearer $REFRESH_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh-xyz789",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Prepare Session

Prepare session for app/container usage. Client-side endpoint - uses session token.

const result = await chat.prepareSession({
  token: sessionToken
});

console.log(result);
const response = await fetch('https://api.oblien.com/ai/session/prepare', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
curl -X POST https://api.oblien.com/ai/session/prepare \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "containerId": "container-abc123",
  "status": "running"
}

Send Message

Send a message in a chat session. Client-side endpoint - uses session token. Supports streaming.

// Regular message
const response = await chat.send({
  token: sessionToken,
  message: 'Hello, how can you help?'
});

console.log(response);

// Streaming message
await chat.send({
  token: sessionToken,
  message: 'Tell me a story',
  stream: true,
  onChunk: (data) => {
    console.log('Chunk:', data);
  }
});
const response = await fetch('https://api.oblien.com/ai/chat/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Hello, how can you help?',
    stream: false
  })
});

const data = await response.json();
console.log(data);
curl -X POST https://api.oblien.com/ai/chat/send \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how can you help?",
    "stream": false
  }'

Response:

{
  "success": true,
  "message": "I can help you with...",
  "tokens": 150,
  "model": "oblien-master"
}

Upload Files

Upload files for a chat session. Client-side endpoint - uses session token.

const result = await chat.upload({
  token: sessionToken,
  files: [file1, file2]
});

console.log(result);
const formData = new FormData();
formData.append('files', file1);
formData.append('files', file2);

const response = await fetch('https://api.oblien.com/ai/chat/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sessionToken}`
  },
  body: formData
});

const data = await response.json();
console.log(data);
curl -X POST https://api.oblien.com/ai/chat/upload \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -F "files=@file1.pdf" \
  -F "files=@file2.jpg"

Response:

{
  "success": true,
  "uploadId": "upload-abc123",
  "files": [
    {
      "name": "document.pdf",
      "size": 245678,
      "type": "application/pdf"
    }
  ]
}

Create Session Token

Generate a token for an existing session. Use this if you created a session without a token initially, or need to regenerate tokens.

const tokens = await chat.createSessionToken('session-abc123');
console.log(tokens);
const response = await fetch('https://api.oblien.com/ai/session/session-abc123/token/create', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const tokens = await response.json();
console.log(tokens);
curl -X POST https://api.oblien.com/ai/session/session-abc123/token/create \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh-xyz789",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Guest Management

Guest sessions allow anonymous users to chat with your agents without authentication. Oblien manages all guest tracking and rate limiting - you just create the session on your backend.

What Oblien Handles:

  • Guest identification (IP + fingerprint tracking)
  • Rate limiting (100K tokens/day, 50 messages/day, 20/hour)
  • Session persistence and cleanup
  • Guest metadata storage

How Guest Identification Works

The SDK tracks guests using both IP address and browser fingerprint:

First Visit:
  IP: 1.2.3.4, Fingerprint: abc123 → Creates Guest ID: guest-xxx

Same User, Different IP (mobile network):
  IP: 5.6.7.8, Fingerprint: abc123 → Matches Guest ID: guest-xxx ✅

Same User, Cleared Browser:
  IP: 1.2.3.4, Fingerprint: xyz789 → Matches Guest ID: guest-xxx ✅

This provides better continuity for users on mobile networks or VPNs.

Create Guest Session

Create a session for an anonymous user. Must be called from your backend. Oblien automatically tracks guests using IP + fingerprint and manages rate limiting.

const guestSession = await chat.createGuestSession({
  ip: req.ip,
  fingerprint: req.body.fingerprint,
  agentId: 'public-agent',
  namespace: 'production',
  endUserId: 'user-789'
});

console.log(guestSession);
const response = await fetch('https://api.oblien.com/ai/session/create', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: 'public-agent',
    is_guest: true,
    namespace: 'production',
    ip_address: '192.168.1.1',
    fingerprint: 'fingerprint-abc123'
  })
});

const session = await response.json();
console.log(session);
curl -X POST https://api.oblien.com/ai/session/create \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "public-agent",
    "is_guest": true,
    "namespace": "production",
    "ip_address": "192.168.1.1",
    "fingerprint": "fingerprint-abc123"
  }'

Response:

{
  "success": true,
  "sessionId": "session-guest-abc",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh-xyz789",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "agentId": "public-agent",
  "namespace": "production",
  "guest": {
    "id": "guest-def456",
    "namespace": "guest-192-168-1-1",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Get Guest

Check if a guest already exists by IP and/or fingerprint. Use this to reuse existing guest sessions.

const existingGuest = await chat.getGuest('192.168.1.1', 'fingerprint-abc123');
console.log(existingGuest);
// Guest lookup is handled by SDK internally
// Use createGuestSession - it automatically handles existing guests
# Guest lookup is handled by SDK internally
# Use createGuestSession endpoint - it automatically handles existing guests

Browser Fingerprinting

Generate fingerprint on the client side and send it to your backend:

// Client-side (browser)
import FingerprintJS from '@fingerprintjs/fingerprintjs';

const fp = await FingerprintJS.load();
const result = await fp.get();
const fingerprint = result.visitorId;

// Send to backend
const response = await fetch('/api/guest-session', {
  method: 'POST',
  body: JSON.stringify({
    fingerprint,
    agentId: 'public-agent'
  })
});

Guest Rate Limits

Oblien automatically enforces rate limits for all guest sessions:

  • 100,000 tokens per day
  • 50 messages per day
  • 20 messages per hour

Limits are per guest ID (tracked via IP + fingerprint). No additional rate limiting code needed on your side.

Storage Options

Default: NodeCache (Recommended)

  • Works out of the box, no setup needed
  • Automatic cleanup of expired guests

Redis (For Multi-Server)

import { createClient } from 'redis';
import { RedisStorage } from 'oblien';

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

const chat = new OblienChat(client, {
  guestStorage: new RedisStorage(redis),
  guestTTL: 86400  // 24 hours
});

Architecture

Session Flow:

Your Backend (Client ID/Secret)
    ↓
Create Session → Oblien API
    ↓
Oblien Manages:
  - Session storage
  - Rate limiting
  - Guest tracking
  - Token generation
    ↓
Returns Token → Your Backend
    ↓
Send Token → Your Frontend
    ↓
Frontend Uses Token → Chat SDK
    ↓
User Interacts with Agent

Key Points:

  • Backend only - Client ID/Secret never leave your server
  • Oblien manages - All session infrastructure handled automatically
  • Frontend gets - Only the session token (safe to expose)
  • No setup - No database, Redis, or session management code needed

Best Practices

Session Creation:

  • Always create sessions on your backend server
  • Never expose Client ID/Secret in frontend code
  • Send only tokens to frontend
  • Store tokens securely (never in URLs or logs)

Guest Sessions:

  • Always send both IP and fingerprint when available
  • Fall back to IP-only if fingerprint unavailable
  • Oblien handles all rate limiting automatically

Security:

  • Validate IP addresses on your backend
  • Sanitize fingerprint data before sending
  • Monitor session creation rates
  • Use refresh tokens to extend session lifetime

Next Steps

  • Chat SDK - Frontend integration for sending messages
  • Agents - Create and configure agents
  • Integration - Framework examples (Express, Next.js)

Core SDK Overview

Backend SDK for all Oblien features - agents, chat, sandbox, search, credits, and more

Tools

Browse, create, and manage AI tools for your agents

On this page

Agent Sessions
Overview
API Usage
Create Session
List Sessions
Get Session Details
Get Session History
Refresh Session Token
Prepare Session
Send Message
Upload Files
Create Session Token
Guest Management
How Guest Identification Works
Create Guest Session
Get Guest
Browser Fingerprinting
Guest Rate Limits
Storage Options
Architecture
Best Practices
Next Steps